企业官网建设流程全解析

• 教程
• 文档

package.json是每个 Node.js 项目根目录下的核心配置文件，它既声明了项目所需的全部模块依赖，也承载了名称、版本、许可证等元数据，并充当 npm 脚本命令的注册表。本文以 jstutorial 仓库中 package.json 文件文档 为骨架，逐字段拆解其含义与用法，并结合本仓库自身的 package.json 与 Gruntfile.js 给出可落地的实战示例。读完本文，你将能够独立编写、生成和维护 package.json，掌握npm install、npm run等命令与配置字段的协作机制，并理解版本范围、脚本钩子、bin 链接等进阶用法。

概述：package.json 是什么

每个项目的根目录下面，一般都有一个package.json文件，它定义了这个项目所需要的各种模块，以及项目的配置信息（比如名称、版本、许可证等元数据）。npm install命令根据这个配置文件，自动下载所需的模块，也就是配置项目所需的运行和开发环境。

下面是一个最简单的 package.json 文件，只定义两项元数据：项目名称和项目版本。

{ "name" : "xxx", "version" : "0.0.0", }

package.json文件就是一个 JSON 对象，该对象的每一个成员就是当前项目的一项设置。比如name就是项目名称，version是版本（遵守"大版本.次要版本.小版本"的格式）。

下面是一个更完整的 package.json 文件。

{ "name": "Hello World", "version": "0.0.1", "author": "张三", "description": "第一个node.js程序", "keywords":["node.js","javascript"], "repository": { "type": "git", "url": "https://path/to/url" }, "license":"MIT", "engines": {"node": "0.10.x"}, "bugs":{"url":"http://path/to/bug","email":"bug@example.com"}, "contributors":[{"name":"李四","email":"lisi@example.com"}], "scripts": { "start": "node index.js" }, "dependencies": { "express": "latest", "mongoose": "~3.8.3", "handlebars-runtime": "~1.0.12", "express3-handlebars": "~0.5.0", "MD5": "~1.2.0" }, "devDependencies": { "bower": "~1.2.8", "grunt": "~0.4.1", "grunt-contrib-concat": "~0.3.0", "grunt-contrib-jshint": "~0.7.2", "grunt-contrib-uglify": "~0.2.7", "grunt-contrib-clean": "~0.5.0", "browserify": "2.36.1", "grunt-browserify": "~1.3.0", } }

可以看到，一个典型的 package.json 由三部分内容组成：描述项目自身的元数据（name、version、author、description、keywords、license等）、声明依赖关系的字段（dependencies、devDependencies、peerDependencies），以及定义运行行为与入口的字段（scripts、bin、main、config等）。

作为真实案例，本仓库根目录的 package.json 就是一个完整的示例：它以"name": "jstutorial"、"version": "0.5.0"、"description": "JavaScript 标准参考教程"描述自身，用"main": "index.md"指明首页入口文档，通过"scripts": { "build": "grunt", ... }将构建任务交给 Grunt，并在devDependencies中列出了grunt、grunt-contrib-uglify等开发期工具。

scripts 字段：用 npm 统一管理命令行任务

scripts指定了运行脚本命令的 npm 命令行缩写，比如start指定了运行npm run start时，所要执行的命令。

下面的设置指定了npm run preinstall、npm run postinstall、npm run start、npm run test时，所要执行的命令。

"scripts": { "preinstall": "echo here it comes!", "postinstall": "echo there it goes!", "start": "node index.js", "test": "tap test/*.js" }

npm run命令会自动在环境变量$PATH中添加node_modules/.bin目录，因此scripts字段里调用命令时不用加上路径，这就避免了全局安装 npm 模块。此外，npm 内置了两个命令简写：npm test等同于执行npm run test，npm start等同于执行npm run start。

本仓库的 package.json 就体现了这个机制：

"scripts": { "build": "grunt", "test": "echo \"Error: no test specified\" && exit 1" }

执行npm run build时，npm 会调用本地node_modules/.bin目录下的 grunt 命令；而对应的 Gruntfile.js 则注册了uglify:target与cssmin:minify两个任务，并通过grunt.registerTask('default', ['uglify:target', 'cssmin:minify'])将它们串联为默认任务。这是典型的"配置声明 + 任务脚本"分工模式：scripts字段是入口，真正的构建逻辑由 Gruntfile 承载。

pre- 与 post- 钩子

npm run为每条命令提供了pre-和post-两个钩子（hook）。以npm run lint为例，执行这条命令之前，npm 会先查看有没有定义prelint和postlint两个钩子，如果有的话，就会先执行npm run prelint，然后执行npm run lint，最后执行npm run postlint。如果执行过程出错，就不会执行排在后面的脚本。

除了用户自定义命令，npm 对内置命令同样提供钩子，常见的有：

• preinstall/postinstall：用户执行npm install命令时，先执行 / 安装结束后执行该脚本；
• prepublish/postpublish：发布模块前 / 后执行；
• preuninstall/postuninstall：卸载模块前 / 后执行；
• preversion/postversion：更改模块版本前 / 后执行；
• pretest/posttest：运行npm test前 / 后执行；
• prestart/poststart：运行npm start前 / 后执行；
• prestop/poststop：运行npm stop前 / 后执行；
• prerestart/postrestart：运行npm restart前 / 后执行。

注意，不能在pre脚本之前再加pre，即prepretest脚本不起作用。postinstall常用于处理从 Git 仓库拉下来的源码——比如有些源码用 TypeScript 编写，需要在安装后编译转换。

内部变量

scripts 字段可以使用一些内部变量，主要是 package.json 的各种字段。比如 package.json 的内容是{"name":"foo", "version":"1.2.5"}，那么变量npm_package_name的值是 foo，变量npm_package_version的值是 1.2.5：

{ "scripts":{ "bundle": "mkdir -p build/$npm_package_version/" } }

运行npm run bundle以后，将会生成build/1.2.5/子目录。

关于npm run的更多用法（参数传递、命令编排、npm-run-all等），可进一步阅读仓库中的 npm 模块管理器文档。

dependencies 与 devDependencies 字段：声明依赖及其版本范围

dependencies字段指定了项目运行所依赖的模块，devDependencies指定项目开发所需要的模块。它们都指向一个对象，该对象的各个成员，分别由模块名和对应的版本要求组成，表示依赖的模块及其版本范围。

{ "devDependencies": { "browserify": "~13.0.0", "karma-browserify": "~5.0.1" } }

对应的版本可以加上各种限定，主要有以下几种：

• 指定版本：比如1.2.2，遵循"大版本.次要版本.小版本"的格式规定，安装时只安装指定版本。
• 波浪号（tilde）+指定版本：比如~1.2.2，表示安装 1.2.x 的最新版本（不低于 1.2.2），但是不安装 1.3.x，也就是说安装时不改变大版本号和次要版本号。
• 插入号（caret）+指定版本：比如^1.2.2，表示安装 1.x.x 的最新版本（不低于 1.2.2），但是不安装 2.x.x，也就是说安装时不改变大版本号。需要注意的是，如果大版本号为 0，则插入号的行为与波浪号相同，这是因为此时处于开发阶段，即使是次要版本号变动，也可能带来程序的不兼容。
• latest：安装最新版本。

npm 采用"语义版本"（semver）管理软件包，版本号为a.b.c的形式，其中a是大版本号，b是小版本号，c是补丁号。一个软件发布的时候，默认就是v1.0.0版；以后发布补丁就增加最后一位数字，增加新功能且不影响原有功能就增加中间的数字，引入破坏向后兼容性的变化则增加第一位数字。需要注意，如果大版本不到 v1.0.0（即 v0.x.y）时，不兼容变动应修改小版本号，即从v0.4.1升级到v0.5.0。

对于~和^，可以这样具体区分：

~2.2.1 // 接受2.2.1，不接受2.3.0 ^2.2.1 // 接受2.2.1和2.3.0 ~2.2 // 接受2.2.0和2.2.1，不接受2.3.0 ^2.2 // 接受2.2.0、2.2.1和2.3.0 ~2 // 接受2.0.0、2.1.0、2.2.0、2.2.1和2.3.0 ^2 // 接受2.0.0、2.1.0、2.2.0、2.2.1和2.3.0

此外，还可以使用数学运算符（比如>、<、=、>=或<=）指定版本范围，例如> 2.1、1.0.0 - 1.2.0、>= 1.0.0-rc.0 < 1.0.1。如果使用连字号，它的两端必须有空格，否则会被 npm 理解成预发布的 tag。*或x则表示接受所有更新。更多语义版本规则可参考仓库中的 版本管理文档。

本仓库的 package.json 正好同时展示了~与^两种写法："grunt": "~0.4.2"表示安装 0.4.x 系列的最新补丁版本，"cz-conventional-changelog": "^1.1.5"表示安装 1.x.x 系列的最新版本。

生成 package.json：npm init

package.json 文件可以手工编写，也可以使用npm init命令自动生成。

$ npm init

这个命令采用互动方式，要求用户回答一些问题，然后在当前目录生成一个基本的 package.json 文件。所有问题之中，只有项目名称（name）和项目版本（version）是必填的，其他都是选填的。

如果使用了-f（代表 force）或-y（代表 yes）参数，则跳过提问阶段，直接生成一个新的 package.json 文件：

$ npm init -y

安装依赖并写入配置

有了 package.json 文件，直接使用 npm install 命令，就会在当前目录中安装所需要的模块。

$ npm install

如果一个模块不在package.json文件之中，可以单独安装这个模块，并使用相应的参数，将其写入package.json文件之中。

$ npm install express --save $ npm install express --save-dev

上面代码表示单独安装 express 模块，--save参数表示将该模块写入dependencies属性，--save-dev表示将该模块写入devDependencies属性。这两个参数也分别可以简写为-S和-D。

相关补充用法：

• npm install --save-exact会在 package.json 中记录模块的确切版本，而不是一个可选的版本范围；也可以预先用npm set save-exact true全局开启这一行为。
• 默认情况下npm install会同时安装dependencies与devDependencies中的全部模块；使用--production参数（或设置环境变量NODE_ENV=production）时，只安装dependencies字段的模块，这正是部署环境常用的做法。
• 用npm config set save-prefix ~可以把--save/--save-dev写入的版本范围从默认的插入号（^）改成波浪号（~），即从"允许小版本升级"变成"只允许补丁包的升级"。

在仓库的 express 文档 中可以看到一个手工编写的实例：dependencies中写入"express": "3.x"，随后执行npm install即可按该版本范围安装框架依赖。

peerDependencies 字段：为插件声明宿主版本

有时，你的项目和所依赖的模块，都会同时依赖另一个模块，但是所依赖的版本不一样。比如，你的项目依赖 A 模块和 B 模块的 1.0 版，而 A 模块本身又依赖 B 模块的 2.0 版。

大多数情况下，这不构成问题，B 模块的两个版本可以并存，同时运行。但是，有一种情况会出现问题，就是这种依赖关系将暴露给用户。

最典型的场景就是插件，比如 A 模块是 B 模块的插件。用户安装的 B 模块是 1.0 版本，但是 A 插件只能和 2.0 版本的 B 模块一起使用。这时，用户要是将 1.0 版本的 B 的实例传给 A，就会出现问题。因此，需要一种机制，在模板安装的时候提醒用户，如果 A 和 B 一起安装，那么 B 必须是 2.0 模块。

peerDependencies字段，就是用来供插件指定其所需要的主工具的版本。

{ "name": "chai-as-promised", "peerDependencies": { "chai": "1.x" } }

上面代码指定，安装chai-as-promised模块时，主程序chai必须一起安装，而且chai的版本必须是1.x。如果你的项目指定的依赖是chai的 2.0 版本，就会报错。

注意，从 npm 3.0 版开始，peerDependencies不再会默认安装了——它仅作为版本兼容性约束存在，npm 会在宿主项目引入版本冲突时给出警告或错误提示。

bin 字段：注册可执行命令

bin项用来指定各个内部命令对应的可执行文件的位置。

"bin": { "someTool": "./bin/someTool.js" }

上面代码指定，someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。npm 会寻找这个文件，在node_modules/.bin/目录下建立符号链接。在上面的例子中，someTool.js 会建立符号链接node_modules/.bin/someTool。由于node_modules/.bin/目录会在运行时加入系统的 PATH 变量，因此在运行 npm 时，就可以不带路径，直接通过命令来调用这些脚本。

因此，像下面这样的写法可以采用简写。

scripts: { start: './node_modules/.bin/someTool.js build' } // 简写为 scripts: { start: 'someTool build' }

所有node_modules/.bin/目录下的命令，都可以用npm run [命令]的格式运行。在命令行下，键入npm run，然后按 tab 键，就会显示所有可以使用的命令；直接运行npm run（不带参数）则会列出 scripts 属性下的全部命令及其对应的脚本内容。

npm run会创建一个 Shell 执行指定的命令，并临时将node_modules/.bin加入 PATH 变量，这意味着本地模块可以直接运行。举例来说，执行npm i eslint --save-dev后，node_modules/.bin目录会生成指向 ESLint 可执行脚本的符号链接node_modules/.bin/eslint，随后就能在scripts里不带路径地写"lint": "eslint ."。这正是"依赖本地安装 + bin 注册"组合出的免全局安装开发流程。

main 字段：指定模块入口文件

main字段指定了加载的入口文件，require('moduleName')就会加载这个文件。这个字段的默认值是模块根目录下面的index.js。

以本仓库的 package.json 为例，"main": "index.md"表示该教程项目的入口文档是根目录的 index.md。而对于普通的 Node 模块来说，main字段的解析规则可以在仓库的 模块加载文档 中看到完整说明：当require发现参数字符串指向一个目录以后，会自动查看该目录的 package.json 文件，然后加载main字段指定的入口文件；如果 package.json 没有main字段，或者根本就没有 package.json 文件，则会加载该目录下的index.js文件或index.node文件。

// package.json { "name" : "some-library", "main" : "./lib/some-library.js" }

config 字段：为脚本提供可配置的环境变量

config字段用于添加命令行的环境变量。

下面是一个package.json文件。

{ "name" : "foo", "config" : { "port" : "8080" }, "scripts" : { "start" : "node server.js" } }

然后，在server.js脚本就可以引用config字段的值。

http .createServer(...) .listen(process.env.npm_package_config_port)

用户执行npm run start命令时，这个脚本就可以得到值。

$ npm run start

用户可以改变这个值。

$ npm config set foo:port 80

注意这里的命名规则：config字段中的键会以npm_package_config_为前缀暴露为环境变量，即config.port对应process.env.npm_package_config_port。这使config成为在 npm 脚本与应用程序之间传递可调参数的标准通道。本仓库的 package.json 也使用了config字段——它把 commitizen 的配置路径放在config.commitizen.path中，供相关工具读取。

其他常用字段

browser 字段

browser 指定该模板供浏览器使用的版本。Browserify 这样的浏览器打包工具，通过它就知道该打包那个文件。

"browser": { "tipso": "./node_modules/tipso/src/tipso.js" },

engines 字段

engines字段指明了该模块运行的平台，比如 Node 的某个版本或者浏览器。

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

该字段也可以指定适用的npm版本。

{ "engines" : { "npm" : "~1.0.20" } }

man 字段

man用来指定当前模块的 man 文档的位置。

"man" :[ "./doc/calc.1" ]

preferGlobal 字段

preferGlobal的值是布尔值，表示当用户不将该模块安装为全局模块时（即不用--global参数），要不要显示警告，表示该模块的本意就是安装为全局模块。它适用于命令行工具类的模块——这类模块的本意就是安装为全局命令，而本地安装会削弱其价值。

style 字段

style指定供浏览器使用时，样式文件所在的位置。样式文件打包工具 parcelify，通过它知道样式文件的打包位置。

"style": [ "./node_modules/tipso/src/tipso.css" ]

小结

package.json是 Node.js 项目的"配置中枢"：元数据字段（name、version、license、author等）描述项目身份，依赖字段（dependencies、devDependencies、peerDependencies）声明模块与版本范围，行为字段（scripts、bin、main、config）则定义命令入口与运行时配置。掌握这些字段后，配合npm init生成配置、npm install --save/--save-dev维护依赖、npm run执行脚本，就能构建出可维护、可部署、可发布的标准 Node.js 项目。仓库中的 package.json 文件文档 与 npm 模块管理器文档 是进一步深入学习的参考入口。

• 教程
• 文档