deployment-verification

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 是最新的且已提交。

验证命令

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

# 清理本地所有 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 中限制版本：

  "engines": {
    "node": ">=20.9.0"
  }
  

包管理器

• packageManager: 在 package.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'

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

pnpm add xyz --filter <project-name>

2. lockfile is not up to date

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

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 强制版本统一。

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