2025年7月27日·1 分钟
用于干净交接的 AI 构建代码库导出检查清单
使用这份 AI 构建的代码库导出检查清单安全交接项目：环境变量、密钥、本地设置、数据库引导、CI，以及清晰的运行 README。
使用这份 AI 构建的代码库导出检查清单安全交接项目：环境变量、密钥、本地设置、数据库引导、CI，以及清晰的运行 README。
大多数导出项目失败有一个简单原因：它们在原始平台内能正常运行，因为默认值、密钥、数据库状态和构建步骤都已经到位。一旦代码离开那个泡泡，下一个开发者就不得不去猜测有哪些假设。
一次干净的交接意味着项目可以被克隆、配置并由没有参与构建的人在一台全新的机器上启动，而不需要长时间的来回沟通。它不要求代码完美，而是要求基础事项明确且可重复。
导出失败通常因为相同的问题反复出现：隐藏的配置、不明确的密钥处理、模糊的本地设置步骤、数据库上的意外情况，以及只在一个环境中才工作的 CI。
这就是为什么 AI 构建的代码库导出检查清单主要关注文档与可重复性，而不是简单地复制文件。如果你在像 Koder.ai 这样的 vibe-coding 平台上构建应用然后导出源代码，下一个团队仍然需要一张地图：该设置什么、运行什么，以及“正常工作”是什么样子。
本检查清单聚焦交接要点：环境变量、密钥、本地开发设置、数据库引导、CI 设置，以及一个实用的“如何运行”的 README。不涉及产品决策、UX 打磨或架构重构。
责任也应该明确。构建方负责把假设显性化（文档、脚本、安全默认值）。接收方负责把项目适配到他们的环境（密钥管理、托管、更严格的 CI 规则）。当双方都清楚自己的职责时，交接就会变成常规操作。
一次干净的交接始于一个简单的约定：代码离开平台时“完成”意味着什么。没有它，团队之后会为缺失脚本、意外依赖或哪个版本才是真正版本而争论。
选择一个单一且稳定的时间点，把它当作事实来源。中途导出会导致仓库几乎能运行却不完全运行。
一个合适的导出时点通常为：
添加一句话说明为什么这是合适的导出时点。例如：“所有核心流程通过，数据库模式对本里程碑已定型。”
写一个简短清单说明接收方应该预期到什么。明确说明哪些包含在内，哪些是有意不包含的。
包含基础项：源代码（应用、服务、共享包）、配置模板（示例 env 文件）、脚本（构建、开发、测试、迁移、填充）、以及部署说明。只有在样本数据已经清洗且安全时才包含样本数据。
然后冻结版本，这样“在我机器上可以运行”就不会成为新的基线。记录运行时和工具链版本（Node、Go、Flutter、包管理器），以及数据库版本（PostgreSQL 的大版本很重要）。
最后列出在运行任何东西之前必须完成的前置事项。保持简短且具体：所需的账号、已安装的工具、必须空闲的端口，以及任何一次性设置步骤。
大多数“在平台上能工作”导出出问题是因为关键配置未被写下来。环境变量是常见罪魁：它们存在仓库外，新团队成员克隆项目后不知道应该设置什么值。
把这当作干净导出的必做项：每个变量都应可被发现、解释清楚并能在不猜测的情况下设置。
在交接 README 中创建一个单一事实来源：列出 env 变量名、它们控制什么、以及值来自哪里。用通俗易懂的语言解释，并标注任何安全相关内容。
每个变量的简单格式：
同时，把一个 .env.example 文件随仓库一起交付。它应包含可能需要的每个变量，并带有安全占位值，以便应用能通过最小修改启动。
# Required
APP_ENV=development
PORT=3000
DATABASE_URL=postgres://user:password@localhost:5432/app_dev
# Optional
LOG_LEVEL=info
CORS_ORIGINS=http://localhost:5173
# Environment specific
PUBLIC_BASE_URL=http://localhost:3000
一些细节能避免大多数混淆：
把“必需与可选”写清楚。如果缺少某个变量会导致崩溃，就说明。如果它启用某个功能（邮件发送、支付、文件存储），请说清楚该功能以及缺失时的表现。
指出每个变量在不同环境下如何变化。DATABASE_URL 和 PUBLIC_BASE_URL 常常在 dev、staging 与 production 间不同，而 LOG_LEVEL 则可能处处相同。如果你使用 Koder.ai 导出并部署，请再次确认平台默认值（端口、基础 URL、允许的来源）已在文档中反映，以便在平台外行为一致。
最后说明本地如何加载 env 变量。如果项目期望一个 .env 文件，说明它位于何处以及应用是自动读取还是需要某个命令/工具来加载。
密钥是如果泄露会造成损害的值：API key、数据库密码、认证令牌、OAuth 客户端密钥、私钥、Webhook 签名密钥等。
对于导出，保持简单：仓库中只应包含占位符，绝不是真实密钥。如果启动需要某个密钥，在 .env.example 中以明显的占位符名称包含它，并解释如何生成真实值。
一种实用模式是把三件事分开：样本文件、本地文件、以及 CI 或部署的密钥存储。导出的代码应包含样本文件、忽略本地文件，并记录 CI/托管如何接收密钥。
为每个环境选择一种方式并坚持使用。
.env（被 gitignore）由应用加载，或团队的本地密钥管理方案示例：仓库里包含 PAYMENTS_API_KEY=replace_me。接收方在服务提供商仪表盘中生成自己的密钥并把它写到本地 .env 与 CI 中。代码保持不变。
交接是轮换密钥的好时机，尤其是在它们曾在共享平台会话中使用过时。
.env 文件。如果你是从 Koder.ai 导出的，把导出当做一个新环境并为接收团队生成新的密钥。
交接成功的标志是新开发者能克隆仓库、运行几条命令并看到应用工作而无需猜测。目标是可预测的前置条件、清晰的命令顺序和与现实一致的简短“如何运行”块。
把这些放在 README 顶部，让没人需要从错误信息里去推断：
如果项目是在 Koder.ai 上构建的，本地设置应与导出的内容保持一致（相同的文件夹结构、相同的启动命令）。不要假设“Postgres 已经在跑”，除非你明确说明。
把新同事应该按顺序运行的精确命令放在这里，保持可复制粘贴：
# 1) Install dependencies
cd web
npm ci
cd ../server
go mod download
# 2) Create your env file
cp .env.example .env
# 3) Start dependencies (if needed)
# e.g., start Postgres locally or via docker compose
# 4) Run the app
cd server
go run ./cmd/api
cd ../web
npm run dev
在其下方添加最小的测试和构建部分：
# Tests
cd server && go test ./...
cd web && npm test
# Build
cd web && npm run build
cd server && go build ./...
大多数“运行不了”的问题归结为几类：
版本不匹配（Node/Go）。症状：依赖或编译错误。解决：安装固定版本并重新安装依赖。
缺少 env 值。症状：配置为 undefined、认证失败、500 错误。解决：对照 .env 与 .env.example 填写必需值。
数据库不可达。症状：连接被拒绝、“数据库不存在”。解决：启动 Postgres，验证 host/port/user，并严格按文档运行数据库初始化步骤。
当项目从平台导出时，数据库通常是第一个在新机器上出问题的地方。目标很简单：队友应该能从“克隆仓库”到“应用带真实数据运行”而无需猜测。
写下针对一个新 PostgreSQL 的最小步骤，并尽可能把命令放在脚本里。你的交接应回答四个问题：
如果你已有脚本（Makefile 目标、shell 脚本、任务运行器命令），优先使用脚本而不是描述手动步骤。如果没有，现在就添加一小套脚本。
在各环境（本地、CI、staging）保持流程一致。一个好的基线如下：
# 1) Create role + database (example names)
createuser app_user --pwprompt
createdb app_db --owner=app_user
# 2) Apply migrations
# Replace with your repo's migration command
./scripts/migrate up
# 3) Seed minimal demo data
./scripts/seed
对于填充数据，优先选择最小的可用数据而不是生产级别的转储。填充脚本应能多次运行（幂等插入，或明确标注“仅在空数据库上运行”）。
对于重置，要对安全性做出明确说明。重置命令应默认仅针对本地开发。如果提供破坏性脚本，添加护栏（例如要求 CONFIRM_RESET=1，或检查 APP_ENV=development）。并定义“重置”意味着什么：删除并重建、清空表，还是恢复已知快照。
当仓库看起来像个杂物箱时，交接会出问题。新来者应该能判断什么重要、什么是生成的、在哪儿修改设置。
提交那些能让项目可重复的内容：锁文件、迁移文件、小型配置模板（如 .env.example）以及任何用于引导应用的脚本。
把个人、生成或敏感文件排除在源码外：本地环境文件、编辑器设置、构建产物、日志、缓存，以及任何授予访问权限的文件（API key、数据库密码、服务账号文件）。
一个简单规则：如果修改会影响所有人，就提交。如果随机器或环境变化，就记录并不提交。
如果你写一段“提交 vs 忽略”的短说明，保持简洁：
README、锁文件、迁移、填充脚本、.env.example.env、密钥文件、构建目录、日志、本地缓存添加一个简短的目录地图，让结构一目了然。例如：“/backend API 服务，/web 前端，/mobile 应用，/db 迁移与填充，/scripts 引导辅助脚本。”
如果你是从 Koder.ai 导出的，把导出当作这次清理的起点：移除生成的杂物，确认忽略规则，并写好目录地图。
当 CI 与本地几乎相同时，交接会安静地失败。如果有人能在笔记本上运行项目，CI 应该运行相同的命令并得到相同结果。
决定每次拉取请求时 CI 必须证明的内容。大多数团队只需一小套：
集成测试与部署步骤也可以，但只有在它们可靠且范围明确时才加入。
让 CI 步骤与本地命令保持接近以避免偏差。如果本地是 make test，CI 也应运行 make test。如果没有 Makefile（或等效任务运行器），考虑添加一个并将其作为共享入口点。
CI 常见的破裂原因是依赖隐藏配置。在 README 中添加一个短节列出 CI 期望的确切变量名。将公共配置与密钥分离。
示例名称（按你的栈调整）：APP_ENV、DATABASE_URL、PORT、JWT_SECRET、S3_BUCKET、STRIPE_API_KEY。在 CI 中，密钥应来自 CI 的密钥存储，绝不应提交到仓库。对于常见的 Go + Postgres 后端，还要指出迁移是否自动运行或需要显式步骤。
决定哪些检查在合并前必需并写下来。“lint + unit tests + build” 通常就够了。如果添加了可选任务（例如移动端构建），除非确实需要，否则把它们设为非阻塞。
还要让 CI 的输出便于排查：打印工具版本并在失败时给出清晰信息。流水线稳定后可以考虑加入缓存。
Maya 收到一个从 Koder.ai 导出的项目。典型配置：React 前端、Go API 和 PostgreSQL 数据库。她应该能克隆仓库并在不猜测的情况下看到工作画面。
她的前 30 分钟流程应该像这样：
.env.example 复制为 .env（或在 shell 中设置相同值），分别为 web 与 api 配置。在混乱的交接中，她通常会遇到三类阻塞问题。
第一：应用启动后崩溃并报出模糊的“缺少配置”错误。真正的问题是未记录的变量，如 AUTH_JWT_SECRET 或要求特定格式的 DATABASE_URL。如果 README 列出每个必需变量、给出安全示例值并说明用途，这就会成为一个快速修复。
第二：API 启动了，但每页显示“无数据”或返回 500 错误。数据库存在但没有表或没有填充数据。干净的交接会提供一到两个可靠命令：运行迁移、填充最小演示数据，并提供重置命令以便出问题时恢复。
第三：一切都在运行，但前端指向了错误端口。Maya 打开了 localhost:3000，但 API 期望 localhost:8080，或 CORS 导致请求被阻止。这时一致的默认配置就很重要：在一个地方设置 WEB_PORT、API_PORT 和 API_BASE_URL，并在 README 中说明本地预期的 URL。
交接只有在别人能从干净克隆运行项目且不需提问时才算完成。证明项目能在平台外存活。
在一台新机器或可丢弃容器上做一次“干净克隆”测试。不要重用已有文件夹、缓存依赖或本地数据库。严格按 README 操作。如果你不得不即兴改动，修正文档或脚本直到不再需要。
能捕捉大多数失败的快速检查：
.env.example 存在，并对每个必需变量提供安全示例值与解释。常见陷阱往往很平凡，因此常被忽视：
下一步：指定一位负责人在 24 到 48 小时内验证导出，而不是几周后。让他们做干净克隆测试并报告差距。
如果你在 Koder.ai（koder.ai）上构建，把这份清单视为常规工作流的一部分：使用 planning 模式写下运行路径，在重大改动前拍快照，并按计划导出源代码，使交接包保持最新。
选择一个稳定点并将其视为事实来源。
至少应包含：
.env.example 和清晰的环境变量文档不要包含任何敏感信息或真实凭据。
在一个地方（通常是根目录 README）记录每个环境变量并随仓库附上 .env.example。
对每个变量列出：
不要提交密钥，只提交占位符。
一个简单方案：
.env.example，使用 replace_me 占位符.env（被 git 忽略）还要记录如何生成每个必需的密钥（例如，“为 生成一个 32+ 字符的随机字符串”）。
对任何可能已共享或重复使用的密钥进行轮换。
一个实用的轮换顺序：
.env把导出视为一个新的环境并从干净状态开始。
让首次运行变成“复制、粘贴、运行”式：
如果项目需要 Docker 或 Make，请明确说明——不要让人从错误信息中去发现它们。
是的——因为 PostgreSQL 的大版本和工具版本会影响行为。
至少记录：
尽量固定版本，并在 CI 中打印版本信息，便于调试失败问题。
提供一个可重现的“从零开始”路径：
为破坏性操作添加护栏（例如要求 APP_ENV=development 或确认标志）。
让 CI 的命令与本地命令靠近并使配置明确。
如果测试需要迁移，说明 CI 是否自动运行迁移或需要显式步骤。
执行一次“干净克隆”测试：
如果你哪怕一次都需要即兴处理，就修复文档或脚本，直到不再需要临时改动。这是最快发现原构建环境隐藏假设（包括像 Koder.ai 之类的 vibe-coding 平台）的方法。
JWT_SECRET