package.json文件详解

package.json 是 Node.js 项目的核心配置文件，定义了项目的元信息、依赖关系、脚本命令等。无论是开发工具还是运行环境，都会依赖这个文件来管理项目的行为。

package.json 的基本结构

一个典型的 package.json 文件包含多个字段，主要分为以下几类：

• 项目元信息：如 name、version、description 等。
• 依赖管理：如 dependencies、devDependencies、peerDependencies 等。
• 脚本命令：如 scripts 字段定义的运行脚本。
• 配置选项：如 browserslist、engines、main 等。

以下是一个简单的示例：

{
  "name": "my-project",
  "version": "1.0.0",
  "description": "A sample Node.js project",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "test": "jest"
  },
  "dependencies": {
    "express": "^4.17.1"
  },
  "devDependencies": {
    "jest": "^27.0.6"
  }
}

项目元信息字段

name 和 version

name 是项目的名称，必须符合 npm 的命名规则（小写字母、数字、连字符或下划线）。version 遵循语义化版本控制（SemVer），格式为 MAJOR.MINOR.PATCH。

{
  "name": "my-awesome-project",
  "version": "1.0.0"
}

description 和 keywords

description 是项目的简短描述，keywords 是一个字符串数组，用于帮助 npm 搜索分类。

{
  "description": "A project to demonstrate package.json",
  "keywords": ["node", "javascript", "demo"]
}

license

license 指定项目的开源许可证，常见的有 MIT、Apache-2.0、GPL-3.0 等。

{
  "license": "MIT"
}

依赖管理字段

dependencies

dependencies 是项目运行时必需的依赖包，安装时会自动下载这些包及其依赖。

{
  "dependencies": {
    "lodash": "^4.17.21",
    "axios": "~0.21.1"
  }
}

版本号前的符号含义：

• ^：允许更新次要版本和补丁版本（如 ^1.2.3 允许 1.x.x，但不允许 2.0.0）。
• ~：仅允许更新补丁版本（如 ~1.2.3 允许 1.2.x，但不允许 1.3.0）。
• 无符号：严格匹配指定版本。

devDependencies

devDependencies 是开发时需要的依赖，如测试框架、构建工具等，不会在生产环境安装。

{
  "devDependencies": {
    "eslint": "^7.32.0",
    "webpack": "~5.52.0"
  }
}

peerDependencies

peerDependencies 用于指定宿主环境必须提供的依赖包，常用于插件开发。

{
  "peerDependencies": {
    "react": ">=16.8.0"
  }
}

optionalDependencies

optionalDependencies 是可选的依赖包，即使安装失败也不会影响项目运行。

{
  "optionalDependencies": {
    "fsevents": "^2.3.2"
  }
}

脚本命令字段

scripts 字段允许定义一系列可运行的命令，通过 npm run <script> 执行。

{
  "scripts": {
    "start": "node server.js",
    "build": "webpack --mode production",
    "test": "jest --coverage",
    "lint": "eslint ."
  }
}

生命周期脚本

npm 提供了一些特殊的生命周期脚本，如 preinstall、postinstall 等，会在特定阶段自动执行。

{
  "scripts": {
    "postinstall": "echo 'Installation completed!'"
  }
}

配置选项字段

main

main 指定项目的入口文件，通常是 index.js 或 lib/index.js。

{
  "main": "dist/index.js"
}

browser

如果项目同时支持 Node.js 和浏览器环境，可以用 browser 指定浏览器端的入口文件。

{
  "browser": "dist/browser.js"
}

engines

engines 指定项目运行的 Node.js 或 npm 版本范围。

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

browserslist

browserslist 定义项目需要支持的浏览器范围，通常用于 Babel 或 Autoprefixer 等工具。

{
  "browserslist": [
    "> 1%",
    "last 2 versions"
  ]
}

其他常用字段

repository

repository 指定项目的代码仓库地址。

{
  "repository": {
    "type": "git",
    "url": "https://github.com/user/repo.git"
  }
}

author 和 contributors

author 是项目的主要作者，contributors 是贡献者列表。

{
  "author": "John Doe <john@example.com>",
  "contributors": [
    "Jane Smith <jane@example.com>"
  ]
}

private

如果项目是私有的，不希望发布到 npm，可以设置 private: true。

{
  "private": true
}

自定义字段

除了标准字段，还可以在 package.json 中添加自定义字段，供工具或脚本使用。

{
  "config": {
    "port": 3000
  },
  "myCustomConfig": {
    "apiUrl": "https://api.example.com"
  }
}

示例：完整的 package.json

以下是一个更完整的 package.json 示例：

{
  "name": "full-example",
  "version": "1.0.0",
  "description": "A complete package.json example",
  "main": "index.js",
  "scripts": {
    "start": "node index.js",
    "build": "webpack",
    "test": "jest",
    "lint": "eslint ."
  },
  "dependencies": {
    "express": "^4.17.1",
    "lodash": "^4.17.21"
  },
  "devDependencies": {
    "eslint": "^7.32.0",
    "jest": "^27.0.6",
    "webpack": "^5.52.0"
  },
  "peerDependencies": {
    "react": ">=16.8.0"
  },
  "engines": {
    "node": ">=12.0.0"
  },
  "browserslist": [
    "> 1%",
    "last 2 versions"
  ],
  "repository": {
    "type": "git",
    "url": "https://github.com/user/full-example.git"
  },
  "author": "Alice <alice@example.com>",
  "license": "MIT",
  "private": true
}