你不需要手动编写这部分内容。 设置环境最简单的方法是启动一个 Devin 会话，让它配置 代码仓库。Devin 会分析该项目，安装依赖，并生成一份配置方案——你在 timeline 的建议卡片上点击 Approve 。本指南适用于以下情况：你想了解 Devin 生成了什么内容、自定义配置，或者从头开始编写配置。
Devin 在自己的 VM 上运行。每次 会话 都会从一个机器镜像 启动——也就是一个已保存的快照，其中预装了你的工具、代码仓库 和依赖。你可以在 设置 > Devin 的环境 中编辑环境配置，来控制这个镜像里包含哪些内容。
你的 environment.yaml 包含三个部分：
Section 目的 运行时机 Executed? initialize安装工具并编译依赖 仅在构建时运行 — 结果会保存到机器镜像中 是 maintenance保持依赖最新，并写入凭据配置 构建时 + 每次 会话 开始时 是 knowledge与环境设置相关的简短说明 (例如，lint/test 命令) 在 会话 开始时加载 否 — 仅供参考
对于任何耗时较长或只需执行一次的操作，请使用 initialize：例如安装包管理器、全局 CLI 工具、编译原生依赖，或添加系统软件包。
结果会保存在机器镜像中，并且 不会 在会话开始时再次运行。
initialize : | curl -LsSf https://astral.sh/uv/install.sh | sh npm install -g pnpm
多行字符串会作为一个启用了 set -e 的 bash 脚本执行，因此任何一行失败都会使构建停止。对于跨多行的命令，请使用 \ 进行续行，或使用带有具名步骤的展开形式 ，这样它们会在构建日志中分别显示。
在保存机器镜像前，secrets 文件会被移除。如果 initialize 中的命令将敏感值写入配置文件 (例如，将认证令牌写入 .npmrc) ，该值可能会保留在镜像中——这会带来安全风险。请改为将写入凭据的步骤放在 maintenance 中，因为每个会话都会重新加载 secrets。
当你需要具名步骤时，请使用列表形式。具名步骤可让构建日志更便于调试——当某些内容失败时，你会看到是哪个步骤出了问题，而不只是一个行号。
initialize : - name : Install uv run : curl -LsSf https://astral.sh/uv/install.sh | sh - name : Install system packages run : | sudo apt-get update -qq sudo DEBIAN_FRONTEND=noninteractive apt-get install -y -qq libpq-dev ffmpeg
你可以混合使用具名步骤和非具名步骤。没有 run 的步骤会被跳过。
要为后续步骤设置环境变量，请将 KEY=VALUE 行写入 $ENVRC 文件 (类似于 GitHub Actions 的 $GITHUB_ENV) 。写入 $ENVRC 的所有变量都会自动导出，供后续步骤和 Devin 会话使用。
initialize : - name : Configure environment run : | echo "NODE_ENV=production" >> $ENVRC echo "CI=true" >> $ENVRC
使用 maintenance 来保持依赖最新，并写入凭据配置文件。
它会在构建期间 (initialize 之后) 运行，并且 会在每次会话开始时 (拉取最新代码之后) 运行。由于它会在每次会话开始时运行，命令应当快速且采用增量方式。
maintenance : | npm install pip install -r requirements.txt
请使用 npm install，不要使用 npm ci。 npm ci 会删除 node_modules，并在每次运行时从头重新安装所有内容。npm install 采用增量更新，在依赖未发生变化时会快得多。
任何将 secrets 写入配置文件 (.npmrc, settings.xml, pip.conf) 的步骤都应放在 maintenance 中，而不是 initialize。这样可以确保凭据在每个会话开始时都是最新的。
maintenance : - name : Install dependencies run : npm install - name : Configure private registry run : npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
将 knowledge 用于记录一些简短的设置信息，这些信息是 Devin 实际使用你刚搭建好的环境所需要的——例如 lint 命令、测试命令，或者如何启动开发服务器。
这与主要的 Knowledge 功能不同。 对于大多数你希望 Devin 记住的内容——架构、规范、易错点、团队工作流程——请使用独立的 Knowledge 功能。它具有更丰富的触发条件，更易于编辑，也更适合存放通用的项目上下文。仅在 environment.yaml 的 knowledge 部分中填写与本文件中的环境设置直接相关的简短说明 (例如：“lint 命令是 npm run lint”) 。这一部分是可选的，而且大多数环境都不需要它。 这些条目是供参考的说明——不会被执行 。请保持简短：
knowledge : - name : lint contents : | Run `npm run lint` to check for errors. Run `npm run lint:fix` to auto-fix. - name : test contents : | Run `npm test` for the full suite. Run `npm test -- --watch` during development. - name : startup contents : | Run `npm run dev` to start the dev server on port 3000.
Devin 支持三个配置层级。每个层级的命令都严格按增量方式叠加 ——它们会在构建期间按顺序运行，较低层级不能覆盖或修改较高层级中的配置。
Level Where to configure What to put here Examples 账户级 (Enterprise)Enterprise Settings > Environment 所有组织 都需要的基础设施 CA 证书、企业代理、VPN、DNS 组织级 Settings > Environment > Organization-wide setup 所有代码仓库共用的工具和设置 语言运行时 (pnpm, uv)、Docker 认证、共享 CLI 工具 代码仓库级 Settings > Environment > [repo] 项目特有的设置和知识 npm install、lint/test/构建 命令、架构说明
如何判断该放在哪里：
如果你的 Enterprise 中每个组织 都需要它 → 账户级
如果你的组织 中每个代码仓库都需要它 → 组织级
如果只有一个代码仓库需要它 → 代码仓库级
你的组织有 一个机器镜像 ——也就是一个 VM 快照，其中预装了你的工具、代码仓库和依赖。所有已配置的代码仓库都会在这同一个镜像中完成克隆和设置。每个会话都会从一个全新的副本启动。
一次构建会按以下顺序创建新的机器镜像：
1. Enterprise config (runs in ~): a. initialize b. maintenance 2. Org-wide config (runs in ~): a. initialize b. maintenance 3. Clone all repositories (up to 10 concurrent) 4. For each configured repo, in the order shown in Settings (runs in ~/repos/<repo-name>): a. initialize b. maintenance 5. Health check, then image is saved
层级是可叠加的 ：仓库级命令可以使用组织级或企业级配置安装的工具。较低层级不能覆盖较高层级的设置。
构建通常需要 5–15 分钟。单个命令会在 1 小时后超时；整个构建会在 2 小时后超时。
每个会话都会启动机器镜像的 全新副本 。会话结束后，所有更改都会被丢弃。
在会话开始时：
会运行 Enterprise 和组织级的 maintenance (在 ~ 中) 。
系统会拉取相关代码仓库的最新代码。
该代码仓库的 maintenance 会再次运行，以捕获自上次构建以来的依赖变更。
该代码仓库的 knowledge 条目会加载到 Devin 的上下文中。
Knowledge 是按代码仓库区分的。 如果你配置了 5 个代码仓库，Devin 只会看到它当前正在处理的那个代码仓库的 knowledge 条目。状态 含义 Success 所有步骤均已完成。机器镜像已就绪。 Partial 某些代码仓库构建失败，但核心构建已成功。会话仍可正常使用，但某些代码仓库可能尚未完全配置好。 Failed 核心构建失败 (例如克隆失败、企业版或组织设置失败) 。 Cancelled 已被较新的构建替代。 Skipped 未检测到配置更改。
在 Environment 设置界面中，代码仓库会显示为三种状态：
状态 含义 Configured 具有包含 initialize/maintenance/Knowledge 的 YAML 配置。已在 machine image 中完成全部设置。 Included 已克隆到 machine image 中，但没有自定义配置。Devin 可以访问代码。 Available 组织 可以访问，但尚未添加到该 Environment 中。未克隆。
Included 与 Configured： “included” 的 代码仓库 已被克隆，因此 Devin 可以访问代码，但没有自定义设置命令。“configured” 的 代码仓库 则具有明确的 initialize/maintenance/Knowledge 指示。在以下情况下，会触发新的构建：
请使用 $VARIABLE_NAME 语法引用 secrets。请在 Settings > Secrets
maintenance : - name : Configure private registry run : npm config set //registry.npmjs.org/:_authToken $NPM_TOKEN
在构建和会话期间，secrets 可作为环境变量使用。保存机器镜像前，secrets 文件会被删除——但如果某个命令在 initialize 期间将敏感值展开并写入配置文件，该展开后的值可能会保留在镜像中。请务必改为在 maintenance 中写入凭据，因为它们会在每个会话中重新加载。
有关 secrets 管理的更多信息，请参阅 Secrets & Site Cookies 。
当你配置多个 代码仓库 时，每个 代码仓库 都会在 Settings 中有各自的 YAML。在 build 期间，它们都会在同一个镜像中完成设置——分别克隆到不同的目录中，并各自独立安装依赖。在 会话 期间，只有 active 代码仓库 的维护和 Knowledge 是 relevant。
如果两个 代码仓库 发生冲突怎么办？ 每个 代码仓库 的命令都会在各自的目录中运行，因此依赖冲突很少见。如果两个 代码仓库 安装了同一个全局工具的不同版本，或修改了共享文件 (如 ~/.bashrc) ，则最后运行的那个会生效。为避免这种情况，请将共享工具的安装放在组织级配置中。对于 monorepo，你只需编写一个 YAML 文件来覆盖所有子项目。使用 subshells 在子目录中运行命令，而不会更改后续步骤的工作目录：
initialize : - name : Install pnpm run : npm install -g pnpm - name : Install uv run : curl -LsSf https://astral.sh/uv/install.sh | sh maintenance : - name : Frontend deps run : (cd packages/frontend && pnpm install) - name : Backend deps run : (cd packages/backend && uv sync) - name : Shared library run : (cd packages/shared && pnpm install) knowledge : - name : structure contents : | Monorepo with three packages: - `packages/frontend` — React app (TypeScript, pnpm) - `packages/backend` — Python API (FastAPI, uv) - `packages/shared` — Shared TypeScript utilities
括号 (cd ... && ...) 很重要——它们会在子 shell 中运行该命令，这样到了下一步骤时，工作目录就会重置。
**何时使用多代码仓库与单代码仓库配置：**如果代码位于一个 Git 代码仓库中，请使用一个包含子 shell 的 YAML。如果代码分布在多个 Git 代码仓库中，请在 Settings 中分别配置每个代码仓库。
YAML 参考 字段参考表、执行细节、预装工具和术语表。
配置示例 适用于 Node.js、Python、Java、Go、monorepo、企业模式等场景的可直接复制粘贴示例。
故障排查与常见问题 排查构建失败、从交互式设置迁移，并查找常见问题的解答。
企业版环境设置 权限、构建级联、多 org 管理和企业版迁移。
