npm 生态系统

npm 是随 Node.js 一起分发的包管理器。它可以安装软件包、运行项目脚本、向注册表发布软件包，并记录依赖项解析结果，以便团队能够复现应用程序构建过程。

包元数据 #

每个 npm 项目都由 package.json 描述。最重要的字段用于标识软件包、定义脚本并声明依赖项：

{
  "name": "example-service",
  "private": true,
  "type": "module",
  "scripts": {
    "test": "node --test",
    "start": "node src/server.js"
  },
  "dependencies": {
    "fastify": "^5.0.0"
  },
  "devDependencies": {
    "typescript": "^5.0.0"
  },
  "engines": {
    "node": ">=20"
  }
}

生产环境需要使用 dependencies。devDependencies 用于支持开发、测试或构建。标记为 private: true 的软件包不会被意外发布。

type 字段控制 .js 文件的解释方式："module" 选择 ECMAScript 模块；省略该字段时，则采用默认的 CommonJS 行为。支持两种模块系统的软件包可以使用 exports 字段公开明确指定的公共入口点。

版本范围和锁定文件 #

npm 版本遵循语义化版本规范：major.minor.patch。^5.2.1 这样的插入号范围允许在下一个主版本发布之前进行兼容的次版本和修订版本更新；~5.2.1 这样的波浪号范围只允许修订版本更新。指定精确版本提供最严格的约束。

package.json 表示允许的版本范围，而 package-lock.json 记录 npm 解析出的精确依赖树。对于应用程序，应同时提交这两个文件，并在持续集成中使用 npm ci。与 npm install 不同，npm ci 要求锁定文件与清单匹配，并安装干净且冻结的依赖树。

npm install
npm run test
npm ci
npm outdated
npm update

脚本和可执行文件 #

npm run <script> 会运行 scripts 字段中的命令，并将 node_modules/.bin 中的本地可执行文件加入 PATH。因此，无需全局安装即可移植地运行 npm run lint。在 -- 后传递参数：

npm run test -- --watch

对于偶尔执行的命令，可以使用 npx <package> 或 npm exec <package>。对于贡献者或 CI 必须反复运行的命令，应优先使用项目依赖和脚本。

注册表和发布 #

公共 npm 注册表是默认注册表，但可以在 .npmrc 中为某个作用域选择注册表：

@acme:registry=https://registry.example.com/

使用在仓库外部管理的令牌进行身份验证，尤其是在 CI 中。发布库之前，应检查 files、.npmignore、exports、许可证以及生成的 tarball：

npm pack --dry-run
npm publish

库应只发布预期的运行时文件，并记录支持的 Node.js 版本。应用程序通常保持私有，通过部署而不是发布来交付。