Node 版本不匹配排查检查清单

这份清单用于排查 Node 版本不匹配。完整流程见 Node 版本不匹配怎么排查。目标是把本地、CI、部署平台和项目声明对齐，而不是随手升级。

适合谁

适合遇到安装失败、构建失败、部署失败，并怀疑 Node 版本不一致的新手。你可以逐项填写，找到真正差异。

也适合项目诊断。客户说项目不能跑时，你可以先用这份清单确认环境，而不是直接改代码。

不适合谁

不适合没看项目要求就全局升级 Node 的人。项目可能要求固定版本。

也不适合混用 npm、pnpm、yarn 的人。包管理器混乱会制造新的锁文件问题。

风险提醒

不要删除锁文件当作第一步。锁文件是团队复现依赖的重要依据。也不要擅自修改客户 CI 或部署平台的 Node 版本，这可能影响线上发布。

如果需要修改 GitHub Actions、Vercel、Netlify 或服务器设置，把它写成客户侧确认事项。

具体步骤

1. 当前版本

• 本地 Node：
• 本地 npm：
• pnpm 或 yarn：
• 操作系统：
• 触发命令：
• 完整报错：

这些是定位的底稿。

2. 项目声明

• package.json engines：
• .nvmrc：
• .node-version：
• README：
• CI 配置：
• 部署平台设置：

如果声明冲突，先记录冲突，再请项目负责人确认。

3. 包管理器

• 使用 npm：
• 使用 pnpm：
• 使用 yarn：
• 锁文件类型：
• 是否出现多个锁文件：
• 是否需要 corepack：

多个锁文件同时存在时，不要随便删除，先确认项目约定。

4. 本地复现

• 切换到目标 Node 版本：
• 重新安装依赖：
• 运行 build：
• 运行 test 或 lint：
• 记录结果：

每一步只改一个变量。否则很难判断问题来自 Node 还是依赖。

5. CI 检查

• GitHub Actions 是否使用 setup-node：
• 版本是否写死：
• 是否读取 .nvmrc：
• 缓存是否按包管理器配置：
• 是否使用同一个锁文件：

CI 和本地不一致时，先记录差异。

6. 部署平台

• 平台名称：
• 项目设置里的 Node 版本：
• 构建命令：
• 安装命令：
• 环境变量：
• 客户是否有权限修改：

部署平台设置通常需要客户或项目管理员确认。

最低交付记录

最低记录包含：本地版本、项目要求、包管理器、锁文件、失败命令、差异判断、建议版本、客户待确认事项。不要只写“Node 版本不对”，要写明哪里不一致。

如果你已经修复，记录验证命令。如果还需要客户修改部署平台设置，写成待办并标明负责人。

客户待办示例

常见客户待办包括：确认部署平台 Node 版本、添加仓库协作者、提供 CI 失败链接、确认是否允许修改 workflow、说明项目约定的包管理器、决定是否升级旧项目依赖。每一项都要写负责人。

待办不要写成“我明天继续修”。更准确的写法是：明日等待客户确认 Vercel 项目 Node 版本；确认后重新运行 build 并记录结果。这样能把你的诊断工作和客户侧配置分开。

如果客户无法确认版本，建议先只交付诊断报告和建议范围，不要直接改生产部署配置。

版本对齐记录

最终记录里建议放一张小表：本地版本、项目声明版本、CI 版本、部署平台版本、建议目标版本。哪一项无法确认，就写“待客户确认”。不要把未知项留空，否则后续复盘时不知道是没检查，还是没有权限查看。

如果你修改了 .nvmrc、package.json engines 或 workflow 里的 Node 版本，要写清楚为什么改，以及是否影响其他开发者。版本对齐是团队约定，不能只看自己本地是否方便。

交付前复核

交付前再做一次反向检查：有没有把 Node 问题误判成依赖问题，有没有同时改动多个锁文件，有没有在未确认权限时改 CI 或部署平台设置，有没有只留下“已修复”却没有验证命令。只要其中一项说不清，就先把它写进复核记录。

给客户的结论建议分三段：已经确认的事实、已经完成的动作、仍需客户确认的事项。这样客户能看懂你做了什么，也能知道下一步卡在哪里。对新手项目练习来说，这比承诺一次性解决所有环境问题更稳。

CTA：下一步

把这份清单复制到排查记录里，先填本地版本和项目声明。需要拆报错用 报错解释器，需要估算修复范围用 项目报价助手。

免责声明

本文是学习和排查流程，不构成法律、安全或职业承诺。真实客户项目需要结合依赖兼容、CI 配置、部署平台、客户授权和人工复核判断。