package.json 文件详解

package.json 是 Node.js 项目的核心配置文件，它记录了项目的元数据、依赖项、脚本命令等信息。无论是简单的命令行工具还是复杂的 Web 应用，都离不开这个文件。本章将深入讲解 package.json 的各个字段及其最佳实践。

1. 什么是 package.json？

package.json 是一个 JSON 格式的文件，位于项目的根目录。它定义了项目所需的各种信息，包括：

项目基本信息：名称、版本、描述、作者、许可证等。
依赖管理：列出项目依赖的包及其版本范围。
脚本命令：通过 scripts 字段定义常用的命令行任务。
入口文件：指定模块的入口文件，供其他模块引用。
配置信息：如引擎版本、私有设置等。

2. 创建 package.json

使用 npm init 命令可以交互式地创建 package.json 文件：

npm init

系统会提示输入名称、版本、描述等信息。如果希望使用默认值快速生成，可以添加 -y 或 --yes 标志：

npm init -y

生成的初始文件示例：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

3. 核心字段详解

3.1 name 和 version

name 和 version 是最重要的字段，它们共同构成一个包的唯一标识。如果要发布到 npm 仓库，这两个字段必须存在且符合规范：

name 必须是小写字母、数字、下划线或连字符，不能包含空格。
version 必须遵循语义版本控制（SemVer）格式，如 1.0.0。

3.2 description

项目的简短描述，有助于在 npm search 时被找到。

3.3 main

指定模块的入口文件。当其他模块通过 require('your-package') 引入时，实际上加载的就是这个文件。默认为 index.js。

3.4 scripts

scripts 字段定义了一组可以通过 npm run 执行的命令。常用的脚本有 start、test、build 等。例如：

{
  "scripts": {
    "start": "node server.js",
    "dev": "nodemon server.js",
    "build": "webpack --mode production",
    "test": "jest"
  }
}

执行方式：npm start、npm run dev、npm run build、npm test。

脚本可以访问 node_modules/.bin 目录下的可执行文件，因此无需全局安装工具。

3.5 dependencies 和 devDependencies

dependencies：生产环境依赖，项目运行时必需的包（如 express、lodash）。使用 npm install <package> --save（或 -S）添加。
devDependencies：开发环境依赖，仅在开发、测试、构建时需要（如 jest、webpack、nodemon）。使用 npm install <package> --save-dev（或 -D）添加。

示例：

{
  "dependencies": {
    "express": "^4.18.0",
    "lodash": "4.17.21"
  },
  "devDependencies": {
    "jest": "^29.0.0",
    "nodemon": "^2.0.20"
  }
}

3.6 peerDependencies

用于指定当前包所依赖的宿主包（host package），通常用于插件开发。例如，一个针对 webpack 的插件可能声明 peerDependencies 要求宿主项目已安装特定版本的 webpack。npm 不会自动安装这些包，但会在安装时给出警告。

{
  "peerDependencies": {
    "webpack": ">=5.0.0"
  }
}

3.7 optionalDependencies

可选依赖，即使安装失败也不会影响整体安装过程。可以使用 #optional 注释，或者通过 npm install --save-optional 添加。

3.8 engines

指定项目运行的 Node.js 或 npm 版本。当使用 npm install 时，npm 会检查当前环境是否满足要求，若不满足会发出警告。

{
  "engines": {
    "node": ">=14.0.0",
    "npm": ">=6.0.0"
  }
}

3.9 private

如果设置 "private": true，npm 会拒绝发布该包，防止意外将私有项目发布到公共仓库。

3.10 author 和 contributors

作者信息，可以是字符串或对象格式。contributors 是贡献者数组。

{
  "author": "John Doe  (https://example.com)",
  "contributors": [
    "Jane Doe "
  ]
}

3.11 license

项目的许可证，建议使用 SPDX 许可证标识符，如 MIT、ISC、Apache-2.0。

3.12 其他常见字段

keywords：字符串数组，帮助用户在 npm 搜索时发现包。
homepage：项目主页的 URL。
bugs：问题跟踪系统的 URL 或邮箱。
repository：代码仓库信息，如 {"type": "git", "url": "..."}。
bin：当包作为命令行工具时，指定可执行文件的映射。
config：用于设置 scripts 中使用的配置参数。

4. 语义版本控制（SemVer）

package.json 中依赖的版本号遵循语义版本控制规范，格式为：主版本.次版本.修订号。可以在版本号前添加符号来指定版本范围：

符号	含义	示例
`^`	允许次版本和修订号升级（兼容次版本）	`"^1.2.3"` 允许 `1.x.x` 且 >=1.2.3
`~`	允许修订号升级（兼容修订号）	`"~1.2.3"` 允许 `1.2.x` 且 >=1.2.3
`>` `>=` `<` `<=`	比较范围	`">=1.2.3 <2.0.0"`
`-`	范围连接符	`"1.2.3 - 2.3.4"`
`latest`	始终安装最新版本（不推荐）	`"latest"`

5. scripts 进阶

除了自定义脚本，npm 还支持一些特殊的脚本名称，它们会在特定时机自动执行，如 preinstall、postinstall、prepublish 等。例如，可以在安装依赖后自动执行某些操作：

{
  "scripts": {
    "preinstall": "node preinstall.js",
    "postinstall": "node postinstall.js"
  }
}

执行 npm install 时会依次触发 preinstall、install（实际安装）、postinstall。

6. package.json 与 package-lock.json

package-lock.json 自动生成，它精确记录了当前安装的每个包的 exact 版本和依赖树结构。这样做的好处是：

确保团队成员或部署环境安装完全相同的依赖版本。
加速 npm install 过程（因为可以直接读取锁文件中的版本信息）。

重要：package-lock.json 应始终提交到版本控制（如 Git）中。

7. 最佳实践

始终锁定依赖版本：提交 package-lock.json，使用 npm ci 而非 npm install 在 CI/CD 环境中。
区分 dependencies 和 devDependencies：确保生产环境只安装必要的包（使用 npm install --production）。
使用语义版本范围：推荐使用 ^ 允许次版本更新，但谨慎对待主版本升级。
保持 scripts 简洁：复杂的脚本可以考虑用单独的脚本文件实现。
填写必要字段：对于发布到 npm 的包，完整的 description、keywords、repository 等有助于用户发现和使用。

提示： 可以使用 npm outdated 查看哪些依赖有新版本，npm update 更新到符合版本范围的版本，npm audit 检查安全漏洞。

小结

package.json 是 Node.js 项目的基石，掌握它的配置对于管理依赖、定义脚本和发布包至关重要。通过本章的学习，你应该能够熟练创建和配置 package.json，理解语义版本控制，并遵循最佳实践来维护项目。下一章我们将深入探讨 package-lock.json 的细节和 npm 的依赖解析算法。

上一章: npm包管理下一章: 创建并发布npm包

Node.js教程