npm 依赖、锁文件与安全配置

npm 是 Node.js 项目常用的包管理器。团队协作的核心不是记住很多命令，而是遵循仓库指定的 Node/npm 版本、package manager 和锁文件。开始前查看 package.json、package-lock.json、.npmrc、README 和 CI 配置，不要随意换工具或重建锁文件。

1. 初始化与依赖范围

npm init -y
npm install <package>
npm install -D <dev-tool>
npm install -O <optional-package>
npm uninstall <package>

本地依赖写入当前项目的 package.json 与 package-lock.json；当前 npm 默认会保存依赖，不需要旧教程常写的 --save。运行应用需要的依赖放 dependencies，构建、测试、lint 工具通常放 devDependencies，只有确实可缺省运行时的依赖才考虑 optionalDependencies。全局安装面向命令行工具，不应把它当成项目代码的依赖解析机制。

版本范围如 ^1.2.3 表示允许符合范围的版本；精确版本或团队统一策略应通过 manifest、lockfile 与仓库约定管理。不要为了追求“最新”手工删除锁文件再安装，这会重算整棵依赖树并造成大规模、难审查的变化。

2. package-lock 与可复现安装

开发时 npm install 会依据 manifest 解析依赖并维护锁文件；提交代码时通常需要把 package.json 与 lockfile 一起提交。CI、Docker 构建和干净部署更适合在锁文件存在且与 manifest 同步时运行：

npm ci

npm ci 按锁文件做干净安装、不会替你修复不匹配的 manifest/lockfile，并会重建 node_modules。它会删除已有 node_modules，不要在含有重要手工文件的目录运行。若创建锁文件时使用了影响依赖树的选项（如 legacy-peer-deps），CI 也要以项目级配置保留相同设置；先确认该设置并非历史遗留的绕过方案。

3. 常用查询与脚本

node --version
npm --version
npm ls --depth=0
npm outdated
npm view <package> version engines repository.url
npm run
npm run build

npm ls 显示当前安装树；npm outdated 是更新候选，不代表应立即升级；npm view 查询 registry 元数据，不能替代对包源码、维护者和许可证的审查。安装新依赖前确认拼写、来源、维护状态、生命周期脚本、体积和许可；npm 包安装过程可能执行依赖脚本。

命令行工具确实需要全局安装时，先检查 Node/npm 的来源和全局 prefix：

npm prefix -g
npm ls -g --depth=0
npm install --global <cli-package>

项目若使用 nvm 等 Node 版本管理器，通常让 CLI 随 Node 版本安装；不要用 sudo 修复 npm prefix 权限，也不要全局安装本应由项目 lockfile 固定的运行依赖。

4. Registry、镜像与认证

查看当前 registry：

npm config get registry
npm config get userconfig

不要照抄旧文章中的 registry.npm.taobao.org：它是历史地址，服务与域名策略可能变化。若网络环境需要镜像，先从当前维护方的官方公告核实 HTTPS 地址、覆盖范围、同步延迟和供应链风险；优先由组织批准的 registry 代理。切换 registry 后检查 lockfile 中是否固定了自定义 tarball URL，避免“改了 registry 但安装仍访问旧主机”。

不要把 _authToken 明文写入仓库的 .npmrc、命令行参数或日志。npm 官方支持在提交的项目 .npmrc 中引用环境变量，例如 //registry.npmjs.org/:_authToken=${NPM_TOKEN}，真实 token 存在 CI 密钥库或本机用户配置中，权限尽量只读、限定 registry 并设置有效期。认证字段必须按 registry host/path 正确 scope，避免向其他 registry 发送凭据。

5. 依赖审计与修复

npm audit
npm audit fix --dry-run

npm audit 报告的是所配置 registry 当前可识别的已知漏洞；没有告警不等于依赖绝对安全。修复前查看受影响路径、可用版本、兼容性和 lockfile diff，再运行测试与构建。npm audit fix --force 允许越出声明范围（包括主版本变化），可能造成破坏性升级；不要把它当作一键清理命令。无法自动修复时记录临时缓解和后续升级计划。

6. 项目换机/CI 检查清单

读取 .nvmrc、.node-version、engines 和 packageManager，按项目选 Node/npm；
保留当前仓库唯一的锁文件和 package manager；
开发用 npm install，CI 在锁文件匹配时用 npm ci；
检查 .npmrc、lockfile tarball 主机和 CI 日志中是否有过期 registry 或秘密；
新增/升级依赖后审阅 manifest/lockfile diff，运行测试、构建和适当的审计。

官方参考：npm install、npm ci、npmrc、Registry、npm audit。