package-lock.json必须提交到git，以确保跨环境依赖版本一致、构建可重现，并防止因npm版本差异导致ci失败或生产报错；不提交将引发“本地能跑、线上崩溃”问题。
防坑不是列清单，而是把高频翻车点变成可执行动作。核心就四件事：锁文件必须提交、npm 版本要统一、依赖树得常看、镜像源不能漏配。
package-lock.json 必须进 Git
这是团队协作中最容易被忽略的“默认开关”。不提交 lock 文件，等于让每个开发者用自己的 npm 版本去重新解析整个依赖树——v6 和 v8+ 的解析策略不同，v8.3 之后才支持 overrides，v10 开始默认启用严格 peer 检查。结果就是本地跑通，CI 报 ERESOLVE，生产直接报 Cannot find module。
- 验证方式：git status | grep package-lock.json，空输出才安全
- 修复动作：删掉 node_modules 和 package-lock.json，用项目约定的 npm 版本重装
- 预防脚本：CI 流程开头加 [ -z \"$(git status --porcelain | grep package-lock.json)\" ] || { echo \"lock file missing\"; exit 1; }
npm 版本统一管理是底线
Node.js 自带 npm，但不同 Node 版本附带的 npm 版本差异很大。比如 Node 18.17 带 npm v9.6，Node 20.15 带 npm v10.8，而 v10.7+ 才默认启用 auto-install-peers。版本错配会导致 lock 文件结构不兼容、peer 依赖自动补全行为不一致、甚至 install 时静默跳过某些子依赖。
将一个或多个视频上传至YouTube。当用户想“上传到YouTube”“发YouTube”“批量上传”“upload to YouTube”“post videos to YouTube”或发布到YouTube时使用此技能。
- 查当前版本：npm -v 和 node -v 一起看
- 锁定方式：在项目根目录放 .nvmrc（内容如 20.15），配合 nvm use；或用 engines 字段写进 package.json
- CI 中强制执行：nvm install $(cat .nvmrc) && nvm use
依赖树不是出问题才看，而是每周扫一遍
npm ls 是唯一能看清“谁真正装了谁”的命令。幽灵依赖、重复 lodash、类型定义冲突，90% 都藏在树里。别等报错再查，养成定期快扫习惯。
- 快速体检：npm ls --depth=0 看顶层直装包是否和 package.json 一致
- 查幽灵依赖：npm ls ，如果路径显示不在 dependencies/devDependencies 里，就是靠提升“碰巧存在”
- 定位冲突：npm ls --all，看是否多个版本共存，再结合 npm explain 查清是谁引入的
国内开发必须配镜像源，且要配对
npm 默认 registry 是 https://registry.npmjs.org/，国内访问不稳定，超时、404、安装中断都是常态。只改 registry 不够，还要确认 disturl 和 node-gyp 源也同步切换，否则遇到 node-sass、sharp 这类编译型包会卡死。
- 推荐配置（npmmirror）：npm config set registry https://registry.npmmirror.com
- 配套设置：npm config set disturl https://npmmirror.com/mirrors/node
- 验证是否生效：npm config list，重点看 registry 和 disturl 两行
