常见 构建 失败的解决方案、常见问题解答，以及从旧版交互式设置迁移的指南。
前往 Settings > Devin’s Environment > Build History。你的构建会显示以下状态之一：
| 状态 | 含义 | 你需要做什么 |
|---|
| Success | 一切正常 | 无需操作——你的机器镜像已准备就绪 |
| Partial | 核心构建已成功，但部分仓库失败 | 检查哪些仓库失败了；对应的会话可能会有问题 |
| Failed | 构建本身失败 | 查看失败步骤的日志 |
| Cancelled | 此构建已被较新的构建取代 | 这是正常情况——如有需要，请启动更新的构建 |
| Skipped | 未检测到配置更改 | 无需操作——此次无需构建 |
- Shared setup — 企业级 + 组织级命令
- Clone — 克隆代码仓库
- Repo setup — 针对各代码仓库的命令
- Finalize — 健康检查和镜像创建
在日志中查找第一个错误。后续错误通常是由第一个错误引发的连带错误。
name 字段的展开形式，日志会准确显示失败的是哪个步骤。这也是为步骤命名的最大优势之一：
# 没有名称 — 难以调试
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
npm install -g pnpm
# 有名称 — 便于定位故障
initialize:
- name: Install uv
run: curl -LsSf https://astral.sh/uv/install.sh | sh
- name: Install pnpm
run: npm install -g pnpm
- 未配置代码仓库访问权限 — 请检查 Enterprise 设置 > 集成
- 私有 代码仓库 需要身份验证令牌
- 代码仓库已重命名或删除
- 网络连接有问题 (需要 VPN 或代理)
修复： 请在你的集成设置中确认 Devin 有权访问该代码仓库。对于私有注册表，请确保已在 Secrets 中配置好凭据。
症状： 在代码仓库设置过程中构建失败，通常发生在 npm install、pip install 或类似步骤。
常见原因：
- 私有包 registry 需要身份验证——将令牌添加到 Secrets
- 包版本冲突——固定到特定版本
- 网络超时——检查是否需要 VPN
- registry URL 配置不正确
修复方法： 在你的 maintenance 部分中添加 registry 身份验证配置。有关私有 registry 的配置模式，请参阅 配置示例。
症状： 构建似乎卡住了，随后失败。
常见原因：
- 交互式提示在等待输入——添加
-y 参数，使用 DEBIAN_FRONTEND=noninteractive
- 依赖项安装量过大，耗时太久
- 命令运行超过 1 小时的超时时限
修复： 为所有安装命令添加非交互参数。将较慢的一次性安装移到 initialize，这样它们只会在构建时运行 (而不是在每次会话中都运行) 。
# 错误 — 将会挂起等待输入
initialize: |
sudo apt-get install libpq-dev
# 正确 — 非交互式
initialize: |
sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev
- 安装系统软件包时缺少
sudo
- 尝试写入受保护的目录
- 文件归属于上一次构建中的其他用户
修复： 对系统级操作 (apt-get、写入 /etc/ 等) 使用 sudo。对于用户级软件包管理器 (npm、pip、cargo) ，通常不需要 sudo。
症状： 在 initialize 中安装的工具，在 maintenance 或后续步骤中无法使用。
常见原因：
- 工具被安装到不在
PATH 中的目录
- 后续步骤没有加载 Shell 配置文件 (
.bashrc) 中的更改
修复： 通过 $ENVRC 将该工具所在目录添加到 PATH：
initialize: |
curl -LsSf https://astral.sh/uv/install.sh | sh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> $ENVRC
- 修复你的 YAML 配置
- 保存——系统会自动启动新的构建
- 查看新构建的日志
先测试命令。 在将命令添加到你的配置之前，先在 Devin 会话中运行一下，确认它能正常工作。这样比等待完整的构建周期更快。
| 错误 | 可能原因 | 修复 |
|---|
command not found | 工具未安装或未加入 PATH | 添加到 initialize，或通过 $ENVRC 加入 PATH |
Permission denied | 缺少 sudo | 安装系统软件包时使用 sudo apt-get install |
npm ERR! 404 | 私有软件包，缺少身份验证 | 在 maintenance 中添加 registry 身份验证令牌 (示例) |
E: Unable to locate package | 未先运行 apt-get update | 在 apt-get install 前添加 sudo apt-get update -qq |
| 超时 | 安装过慢或出现交互式提示 | 移到 initialize；添加 -y 和 DEBIAN_FRONTEND=noninteractive |
| 会话开始后配置文件为空 | 在 initialize 中写入了凭据 | 将凭据相关步骤移到 maintenance |
| 构建成功但会话异常 | maintenance 命令在会话开始时执行失败 | 在会话中手动测试你的 maintenance 命令 |
如果你当前使用的是旧版交互式设置 (即分步向导) ，可以迁移到声明式配置，以获得更好的可复现性以及对多仓库的支持。
旧版设置和声明式配置各自都会生成自己的机器映像。会话只会使用其中之一，绝不会混用。一个名为 “Use legacy machine snapshot” 的组织级开关决定使用哪种映像：
- 开关开启 (默认) ——所有会话都使用旧版快照。不会造成中断。
- 开关关闭 ——所有会话都使用声明式快照。
这意味着，你可以并行配置和测试声明式设置，而其他人仍可继续使用旧版快照工作。
准备配置
记下你当前交互式设置中的命令——你需要将它们映射到 YAML 的各个部分：| 旧版向导步骤 | 声明式对应项 |
|---|
| Git pull | 自动 (内置) |
| 配置 secrets | Secrets (不变) |
| 安装依赖 | initialize 部分 |
| 维护依赖 | maintenance 部分 |
| 设置 lint | 名为 lint 的 knowledge 条目 |
| 设置测试 | 名为 test 的 knowledge 条目 |
| 运行本地 app | 名为 startup 的 knowledge 条目 |
| 其他说明 | 名为 notes 的 knowledge 条目 |
编写 YAML
前往 Settings > Devin’s Environment 并选择你的代码仓库。将旧版命令映射如下：# 旧版“安装依赖” → initialize
initialize: |
nvm use 18
npm install -g pnpm
# 旧版“维护依赖” → maintenance
maintenance: |
pnpm install
# 旧版“设置 lint/测试/app/说明” → knowledge
knowledge:
- name: lint
contents: |
pnpm lint
- name: test
contents: |
pnpm test
- name: startup
contents: |
pnpm dev (port 3000)
- name: notes
contents: |
提交前始终先运行 lint。
保存并等待构建完成
保存你的配置。构建会自动开始。你可以在 Build History 中查看进度。构建是免费的——不会消耗 ACU。
切换前先测试
在为所有人迁移之前，先使用 manual override 在单个会话上测试声明式设置。这样，你 (或负责迭代配置的人) 可以使用声明式快照，而其他人仍继续使用旧版快照。持续迭代配置，直到声明式设置与你的旧版环境完全一致。
完成切换
确认无误后，在你的组织设置中将 OFF 切换到 “Use legacy machine snapshot”。此后，所有新会话都将使用声明式快照。
交互式身份验证流程 (例如 AWS SSO 浏览器登录、需要浏览器的 OAuth 流程) 无法在声明式格式中复现。如果你的旧版设置使用基于浏览器的身份验证，则需要先将这些流程改为无头替代方案 (API key、服务账户令牌等) ，然后再迁移。将凭据添加到 Secrets 中，并在你的 maintenance 部分中引用它们。
- 先配置企业级 YAML —— 包括 VPN、证书和代理设置等共享基础架构。
- 每次迁移一个组织。 每个组织都有各自的旧版切换开关，因此你可以逐步迁移，而不影响其他团队。
- 考虑设立测试组织。 对于大型企业，建议创建一个专用的测试组织，先验证声明式配置，再推广到生产组织。
- 利用 Devin 实现规模化配置。 Devin 可以通过并行会话配置代码仓库 —— 为每个代码仓库启动一个会话，Devin 会自动生成配置建议。这种方式非常适合为 10–100+ 个代码仓库完成接入。
你的旧快照会被保留。如果新的声明式构建失败，Devin 会回退到最近一次成功的快照 (这可能是你的旧版快照) 。你也可以通过 Build History 恢复之前的快照。
| Feature | 旧版 (交互式) | 声明式 (YAML) |
|---|
| 可复现性 | 有状态——快照中的更改会随时间不断累积 | 可完全通过 YAML 复现 |
| 多仓库 | 一次只能处理一个仓库 | 一次构建中可包含多个仓库，并支持并行克隆 |
| 维护 | 手动执行“维护依赖”步骤 | 自动——maintenance 会在会话开始时运行 |
| Enterprise/组织 层级 | 不支持 | 三级层级 (Enterprise → Org → 代码仓库) |
| Devin 建议 | 仅在向导中提供 | 在会话中提供——Devin 可建议更新配置 |
| 成本 | 向导会话会消耗 ACU | 设置会话约消耗 1–3 ACU；构建免费 |
如果我在一个尚未设置好的 代码仓库 上运行 会话，会发生什么？
Devin 仍然可以工作——只是它每次都需要从头识别你的项目。这意味着要花时间安装依赖、了解如何构建和测试，并推断项目所用的规范。因此，会话 会更耗时，也会消耗更多 ACU。设置好环境后，Devin 在每次 会话 开始时都会预先配置完成，可直接使用。
一次构建需要多长时间？
通常需要 5–15 分钟，具体取决于 代码仓库 数量和依赖规模。构建会在 2 小时后超时。
这要花多少钱？
构建是免费的——不会消耗 ACU。如果你使用 Devin 会话 来设置 代码仓库 (例如让 Devin 生成配置) ，该 会话 通常会消耗 1–3 个 ACU。配置保存后，基于该配置的后续构建都是免费的。
我可以同时使用 旧版 和声明式设置吗？
一个 组织 在同一时间只能使用一种模式，由 “Use legacy machine snapshot” 开关控制。你可以在开关仍然开启 (旧版 模式) 时并行配置声明式设置，准备好后再切换。详情请参阅迁移指南。
我可以在不影响其他用户的情况下测试声明式设置吗？
可以。你可以在单个 会话 上使用 manual override，临时启用声明式快照，同时其他人继续使用 旧版 快照。对于 Enterprise，你还可以创建一个专门的测试 组织。
如果我的构建失败了，会发生什么？
Devin 会使用最近一次成功的快照。构建失败不会影响现有 会话。
我应该什么时候使用 initialize，什么时候使用 maintenance？
initialize 用于一次性的工具安装 (apt-get install、语言运行时设置、全局 CLI 工具) 。maintenance 用于需要持续保持最新的依赖安装 (npm install、pip install、uv sync) 。
如何添加环境变量？
将它们写入 $ENVRC：
initialize: |
echo "MY_VAR=value" >> $ENVRC
initialize 部分中使用 sudo apt-get install。务必使用 DEBIAN_FRONTEND=noninteractive 和 -y 标志，以避免出现交互式提示。
如果我需要为不同的 代码仓库 使用不同的 Node 版本，该怎么办？
在 代码仓库 级配置中使用 nvm：
initialize: |
nvm install 18
nvm use 18
- 无构建预览/沙箱 —— 每次配置更改都会触发一次完整构建。请先在会话中测试命令。
- 串行代码仓库设置 —— 代码仓库级别的设置一次只能运行一个 代码仓库 (按字母顺序) 。代码仓库数量越多，构建耗时越长。
- YAML 不支持条件逻辑 —— 该格式不支持 if/else。如有需要，请在命令中使用 shell 条件判断 (例如：
[ -f package.json ] && npm install) 。
- 不支持搜索构建日志 —— 构建日志必须手动滚动查看。请使用具名步骤，以便更容易定位失败位置。
- 环境配置 — 编写配置的主要指南
- 配置示例 — 按技术栈和层级分类的复制粘贴示例
