> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 迁移到声明式配置

> 将经典环境配置迁移为声明式蓝图。Devin 可为你完成大部分迁移工作。

声明式配置 (蓝图) 是新一代的环境配置方式：支持版本控制、可组合，并可自动更新。本指南将引导你从经典的交互式向导迁移过来。

<Warning>
  经典环境配置即将弃用。有两个日期需要注意：

  * \*\*2026 年 6 月 30 日：\*\*所有组织都将迁移到声明式配置 (蓝图)。你的经典配置不会被删除，并且你可以回退到该配置。
  * \*\*2026 年 7 月 31 日：\*\*在此日期之前，你的经典机器配置仍会作为参考保留，方便你在完成迁移期间查阅或回退到该配置。7 月 31 日之后，它将被移除。

  请在 2026 年 6 月 30 日前完成迁移，以避免中断。需要更多时间的 Enterprise 客户应联系其账户团队。
</Warning>

<div id="why-migrate">
  ## 为什么要迁移？
</div>

使用经典设置向导时，Devin 的环境是一个手动配置的快照，随着时间推移可能会逐渐偏离预期。依赖会老化，配置变更需要重新运行向导，而且没有版本历史。声明式配置可以解决这些问题：

* **自动更新**：当你的仓库发生变化时，蓝图会自动重建，因此依赖始终保持最新
* **版本受控**：你的环境配置与代码一同存放，并保留完整的历史记录
* **可组合**：企业、组织和仓库蓝图可以清晰地分层组合
* **可复现**：每次构建都会基于同一个蓝图生成相同的结果
* **更快的会话**：快照会预先构建好，仓库已克隆、依赖已安装，因此会话启动后即可开始工作

<Info>
  你的经典设置会持续可用到 2026 年 6 月 30 日，此后到 2026 年 7 月 31 日前仍可用于迁移，并且在此之前你可以将你的组织切换回该设置。
</Info>

<div id="before-you-start">
  ## 开始前
</div>

<AccordionGroup>
  <Accordion title="检查你的组织是否符合条件">
    在 **Machine Configuration** 页面 (经典设置页面) 查找是否有一条横幅提示，内容为 **“切换到声明式环境配置”**。如果你看到了，就说明你的组织符合条件。

    如果你没有看到这条横幅提示，说明你的组织尚未启用声明式配置。该功能正在逐步推出。请联系你的企业管理员或支持团队。
  </Accordion>

  <Accordion title="谁可以迁移">
    迁移需要 **组织管理员** 权限 (`ManageOrgSettings`) 。如果你不是组织管理员，你会在迁移页面看到“需要管理员权限”的提示。
  </Accordion>

  <Accordion title="可以回退吗？">
    可以，在 2026 年 7 月 31 日之前都可以。你现有的快照会被保留，因此你可以在那之前回退，让你的组织切换回该快照。2026 年 6 月 30 日之后，所有组织都将使用声明式配置，不过在 2026 年 7 月 31 日之前，你的经典机器配置仍可用于回退。
  </Accordion>
</AccordionGroup>

<div id="migration-steps">
  ## 迁移步骤
</div>

<div id="1-go-to-the-migration-page">
  ### 1. 前往迁移页面
</div>

前往 **设置 > 环境迁移**，或点击“Machine Configuration”页面横幅上的 **Get started**。

<div id="2-enable-declarative-configuration">
  ### 2. 启用声明式配置
</div>

点击 **为组织启用**。这会将你的组织切换为在新会话中使用基于 蓝图 的快照。

<Info>这不会影响你现有的快照。系统会保留该快照，以便你在需要时回退。</Info>

<div id="3-let-devin-generate-your-blueprints">
  ### 3. 让 Devin 生成你的蓝图
</div>

**Devin 会替你完成这些工作。**

点击 **开始迁移**，然后选择你想先迁移的代码仓库。你不需要一次性迁移所有内容。先从你最常用的代码仓库开始。

开始迁移后，Devin 会创建 **两个会话**：

* 一个在新的声明式环境中运行的**主会话**，负责编写蓝图
* 一个在你现有快照中运行的**辅助会话**，Devin 用它来检查当前已安装的内容 (语言版本、系统软件包、正在运行的服务等)

Devin 会检查你现有的快照，识别其中已安装的工具和依赖，并生成对应的蓝图配置。结果会显示在你的 **设置 > 环境 > 蓝图** 页面上。

<Tip>
  你现有的快照就像一个“黑盒”，包含了你长期以来配置的所有内容。Devin 会检查该快照，梳理已安装的内容，并自动将其整理为可复现的蓝图。
</Tip>

<div id="4-review-and-adjust">
  ### 4. 检查并调整
</div>

在 Devin 生成蓝图后：

1. 前往 **设置 > 环境 > 蓝图** 查看已生成的内容
2. 检查构建状态，确认显示为 **Success**。
3. 启动一个测试会话，验证一切是否正常：
   * 确认 代码仓库 已克隆，且依赖已安装
   * 尝试运行你的 lint、test 和 build 命令
   * 验证任何自定义工具或运行时是否可用

如果缺少某些内容，请直接编辑蓝图。你可以添加 `initialize` 步骤、`maintenance` 命令或 `knowledge` 条目。

<div id="rolling-back">
  ## 回滚
</div>

如果出现问题，你可以在 2026 年 7 月 31 日之前回退：

1. 前往 **设置 > 环境迁移**
2. 点击 **恢复为经典**
3. 你的组织会立即切换回之前的快照

你现有的快照会被完整保留，不会丢失任何内容。准备好后，你可以随时再次尝试迁移。

<Info>
  在 2026 年 6 月 30 日之后，所有组织都将运行在声明式配置上，但你的经典机器配置在 2026 年 7 月 31 日被移除之前仍可用于回退。需要更多时间的 Enterprise 客户应联系其账户团队。
</Info>

<div id="mapping-classic-setup-steps-to-blueprints">
  ## 将经典设置步骤映射到蓝图
</div>

如果你更愿意手动编写蓝图 (或想了解各项是如何对应的) ，下面是经典向导步骤与蓝图的对应关系：

| 经典设置步骤   | 蓝图中的对应项                          | 说明                                                  |
| -------- | -------------------------------- | --------------------------------------------------- |
| Git pull | *自动*                             | 蓝图会自动处理 git clone 和 pull                            |
| Secrets  | 蓝图编辑器中的 Secrets 选项卡              | 在每个蓝图编辑器中的 **Secrets** 选项卡内进行配置                     |
| 安装依赖     | `initialize`                     | 一次性设置：语言运行时、系统软件包、全局工具                              |
| 维护依赖     | `maintenance`                    | 在会话开始时向 Agent 提供的依赖命令：`npm install`、`pip install` 等 |
| Lint     | `knowledge` (`name: lint`)       | 仅供参考，不会在构建期间执行                                      |
| Test     | `knowledge` (`name: test`)       | 仅供参考，不会在构建期间执行                                      |
| 运行应用     | `knowledge` (`name: dev-server`) | 仅供参考，不会在构建期间执行                                      |
| 其他说明     | `knowledge`                      | 供 Devin 使用的自由格式条目                                   |

<div id="example">
  ### 示例
</div>

**经典设置：**

* 安装依赖：`nvm use 20 && npm install`
* 更新依赖：`npm install`
* 代码检查：`npm run lint`
* 测试：`npm test`
* 运行应用：`npm run dev`

**对应的蓝图：**

```yaml theme={null}
initialize: |
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
  source ~/.bashrc
  nvm install 20

maintenance: |
  npm install

knowledge:
  - name: lint
    contents: npm run lint
  - name: test
    contents: npm test
  - name: dev-server
    contents: npm run dev
```

<div id="troubleshooting">
  ## 故障排查
</div>

<AccordionGroup>
  <Accordion title="构建失败">
    检查构建日志中的具体报错。常见原因：

    * 某个命令在经典设置终端中可用，但在构建上下文中无法运行 (例如需要加上 `-y` 标志的交互式提示)
    * 缺少 secrets (请确保已在 蓝图 编辑器内的 **Secrets** 选项卡中配置好 secrets)
    * 将你的 蓝图 命令与原始命令进行对比，找出差异
  </Accordion>

  <Accordion title="sessions 中缺少依赖">
    请确保你的 `maintenance` 部分包含与经典 **Maintain Dependencies** 步骤相同的依赖安装命令。像 `npm install` 或 `pip install -r requirements.txt` 这样的命令
    应该放在 `maintenance` 中，而不是 `initialize`。
  </Accordion>

  <Accordion title="Devin 不知道如何运行 lint 或测试">
    检查你的 `knowledge` 部分是否包含名为 `lint` 和 `test` 的条目，并且命令正确。Devin 在验证工作结果时会查找这些名称。
  </Accordion>

  <Accordion title="自定义 shell Profile 更改未应用">
    如果你的经典设置修改了 `~/.bashrc`、`~/.profile` 或其他 shell 配置，请将这些内容移到 `initialize` 中：

    ```yaml theme={null}
    initialize: |
      echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
      echo 'export NODE_ENV=development' >> ~/.bashrc
    ```
  </Accordion>

  <Accordion title="Git pull 无法使用">
    蓝图 会在构建期间自动处理 git clone。如果 代码仓库 没有被克隆，请检查它们是否已添加到 **设置 > 环境 > 蓝图** 页面，并确认 Devin 已通过你的 Git integration 获得访问权限。
  </Accordion>
</AccordionGroup>

<div id="related-pages">
  ## 相关页面
</div>

* [声明式环境配置](/zh/onboard-devin/environment/blueprints)
* [蓝图参考](/zh/onboard-devin/environment/blueprint-reference)
* [模板库](/zh/onboard-devin/environment/templates)