AgentSkillsCN

deployment-verification

在将开发环境部署至生产环境前，需遵循验证清单与最佳实践，重点关注单体仓库的依赖管理与环境一致性。

SKILL.md
--- frontmatter
name: deployment-verification
description: 开发环境部署到生产环境前的验证清单与最佳实践，重点关注 Monorepo 依赖管理与环境一致性。

Deployment Verification Skill

用于指导从本地开发环境部署到生产环境（如 Railway, Vercel）时的验证步骤，特别针对 Monorepo 架构下的常见问题。

使用场景

当进行以下操作时，请参考此规范：

  • •首次配置生产环境部署
  • •引入新的第三方依赖
  • •升级 Node.js 或关键工具链版本
  • •处理 "本地能跑，线上挂了" 的构建错误

验证规范

目录

  1. •依赖完整性验证 (Phantom Dependencies)
  2. •环境一致性验证
  3. •构建流程验证
  4. •常见错误与修复

依赖完整性验证

在 Monorepo (TurboRepo/PNPM) 中，最常见的部署错误是幽灵依赖 (Phantom Dependencies)。

现象

本地开发正常运行，但线上构建失败，报错 Cannot find module 'xxx'。

原因

本地包管理器（尤其是 PNPM 在宽松模式下或通过 Workspace）可能允许代码访问未在当前 package 的 package.json 中显式声明的依赖（例如兄弟 package 的依赖）。 生产构建通常是纯净环境（Clean Install），严格遵循 package.json，因此构建失败。

检查清单

  • • 显式声明: 检查代码中 import 的所有第三方库是否都列在当前 apps/*/package.json 或 packages/*/package.json 的 dependencies 中。
  • • Peer Dependencies: 检查是否有未满足的 peer dependencies 警告。
  • • Lockfile: 确保 pnpm-lock.yaml 是最新的且已提交。

验证命令

在本地模拟严格环境进行验证：

bash
# 清理本地所有 node_modules (慎用，需重新安装)
pnpm clean 
# 或者手动删除
rm -rf node_modules apps/*/node_modules packages/*/node_modules

# 重新安装（确保 lockfile 一致）
pnpm install --frozen-lockfile

# 针对特定应用构建
pnpm build --filter <app-name>

环境一致性验证

确保本地开发环境与生产容器环境的基础配置一致。

Node.js 版本

生产环境（如 Railway, Vercel）通常有默认的 Node 版本（往往较旧）。

  • • .nvmrc: 在项目根目录创建 .nvmrc 指定版本（如 20）。
  • • engines 字段: 在 package.json 中限制版本：
    json
    "engines": {
  "node": ">=20.9.0"
}

包管理器

  • • packageManager: 在 package.json 中锁定包管理器版本：
    json
    "packageManager": "pnpm@9.x.x"
  • • Lockfile: 严禁混用 package-lock.json (npm) 和 pnpm-lock.yaml。确保只有 pnpm-lock.yaml 存在。

构建流程验证

构建脚本

检查 turbo.json 和 package.json 中的构建脚本。

  • • 环境变量: 构建过程是否依赖某些环境变量（如 NEXT_PUBLIC_API_URL）？如果是，确保在构建时能获取到（Build Arguments）。
  • • Type Check: 构建命令是否包含 tsc 类型检查？
  • • Lint: 建议在构建前运行 Lint。

常见错误与修复

1. Module not found: Can't resolve 'xyz'

修复: 在报错的子项目中显式安装该依赖。

bash
pnpm add xyz --filter <project-name>

2. lockfile is not up to date

修复: 本地重新安装并更新 lockfile。

bash
pnpm install
# 提交变更
git add pnpm-lock.yaml

3. Node 版本不匹配

错误: You are using Node.js 18.x.x. For Next.js, Node.js version ">=20.9.0" is required. 修复: 添加 .nvmrc 并推送到远程。

4. 依赖冲突 (React 19 vs 18)

错误: ERR_PNPM_PEER_DEP_ISSUES 修复: 在根目录 package.json 使用 pnpm.overrides 强制版本统一。

json
"pnpm": {
  "overrides": {
    "react": "19.0.0",
    "react-dom": "19.0.0"
  }
}