教程 · 编程上线
换台电脑就构建失败：锁 Node 版本再清缓存重装
用版本文件和依赖锁把本地与 CI 的 Node 版本对齐，解决因版本差异导致的构建失败。
前置：项目在另一台电脑或 CI 上构建失败，本地可以正常构建。
材料：项目代码、版本管理工具、CI 配置、锁文件
材料：项目代码、版本管理工具、CI 配置、锁文件
步骤
1. 先看报错和版本要求
记录报错信息里的模块和语法，再看 package.json 的 engines 字段；版本不匹配的报错往往指向某个新语法或原生模块。
2. 在项目里写死版本
加 .nvmrc 或 .node-version 文件写明版本号，让版本管理工具自动切换；只写在文档里，没人会记得切换。
3. 锁住包管理器版本
在 package.json 里声明 packageManager 字段，统一使用同一版本的管理器；npm、pnpm、yarn 混用会生成不同结构的依赖树。
4. 清缓存后按锁文件安装
删掉依赖目录和缓存，用锁文件重新安装，不要用会改写锁文件的命令；锁文件被悄悄升级，问题会继续出现，装完核对版本号。
5. 让 CI 使用同一版本
在 CI 配置里指定和本地一致的版本，并缓存依赖；本地和 CI 不一致，等于每次都在赌，版本写进配置文件。
做完检查
- 本地和 CI 的 Node 版本一致
- 按锁文件安装后构建通过
- package.json 里写明了版本要求
常见错误
- 直接升级到最新大版本，引入不兼容
- 删掉锁文件重装，依赖版本全变
- 忽略 engines 警告
相关工具
同类教程
本地能跑线上 404：先查文件名大小写，再查构建产物
定位大小写、扩展名和路径别名导致的资源 404，用构建产物和大小写敏感环境验证修复。
查看 →密钥被打进了前端包：先分清公开变量和私密变量
识别构建时被内联到前端的变量，把密钥移到服务端并轮换已泄露的凭证。
查看 →单页应用刷新就 404：把未知路径回退到 index.html
配置服务器或托管平台的路由回退规则，让前端路由的深链接刷新和直接访问都能正常打开。
查看 →更新时间：2026-10-29 · 平台规则/软件版本会变；操作前保留原件，以实际页面为准。
跨库学习路径
按共同关键词匹配，不是随机推荐；从任务到提示词/教程/项目继续走。