package.json 详解

本文是对 Node.js 项目中 package.json 文件的详解。

目录

• package.json 简介
• 配置说明
  • 必需属性
  • 可选属性

package.json 简介

package.json 是一个位于 Node.js 项目根目录中的 JSON 文件，管理整个项目的依赖项和元数据，是项目的核心。

NPM 或 YARN 这类包管理工具可以通过 package.json 来识别项目并了解如何处理项目的依赖关系。

配置说明

必需属性

• name
  项目名称，全部小写字母，不能超过 214 个字符且必须是 URL 安全的（允许使用下划线和中横线，但不允许使用空格或其它字符）。

• version
  版本号，格式 x.y.z，符合 NPM 语义版本控制要求。

  • x：主版本号，新增功能，不兼容之前版本
  • y：次版本号，新增功能，但兼容之前版本
  • z：PATCH 补丁版本号，修复 BUG，且兼容之前版本

可选属性

• license
  软件许可证，值通常是许可证的标识符代码，如 BSD、MIT。

• author
  一个人，软件作者，格式：

  • Name 格式字符串

  "author": "Jon Church jon@example.com https://www.osioslabs.com/#team"
  

  • 包含 name、email 和 url 的 JSON，如：

  "author": {
      "name": "...",
      "email": "example@example.com",
      "url": "https://..."
  }
  

• contributors
  一组人，数组类型，数组中每项和 author 格式一致。

• private
  如果这个属性被设置为 true，NPM 将拒绝发布它，这是为了防止一个私有模块被无意间发布出去。如果只想让模块被发布到一个特定的 NPM 仓库，如一个内部的仓库，可与在下面的 publishConfig 中配置仓库参数。

• publishConfig
  这个配置是会在模块发布时用到的一些值的集合。如果不想模块被默认被标记为最新的，或者默认发布到公共仓库，可以在这里配置 tag 或仓库地址。

• description
  字符串，用于 npm search 搜索。

• keywords
  字符串数组，用于 npm search 搜索。

• main
  指定加载的入口文件，使用 require('moduleName') 时便会加载此文件，默认值为模块根目录下的 index.js。
  browser 环境和 node 环境均可使用。

• browser
  定义了 NPM 包在 browser 环境下的入口文件。

• scripts
  指定运行脚本命令的 NPM 命令行缩写，比如 serve 指定了运行 npm run serve 时真正执行的命令。

  以下设置指定了运行 npm run serve、npm run lint、npm run mock 时要执行的命令。

  "scripts": {
      "serve": "concurrently \"npm:mock\" \"vue-cli-service serve\"",
      "lint": "vue-cli-service lint",
      "mock": "cd mock && ts-node-dev mock-server.ts"
  }
  

• config
  用于添加命令行环境变量，JSON 对象，值在 Scripts 的整个周期中皆可用，专门用于给 Scripts 提供配置参数。

• bin
  指定各内部命令对应的可执行文件的位置。如以下配置指定 someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。

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

  NPM 会查找这个文件，在 node_modules/.bin/ 目录下建立符号链接 node_modules/.bin/someTool，由于 node_modules/.bin/ 目录在运行时加入系统的 PATH 变量，因此运行 NPM 时可以不带路径，直接通过命令运行这些脚本。

  所有 node_modules/.bin/ 目录下的命令都可以使用 npm run [命令] 执行，在命令行下键入 npm run 后按 Tab 键就会显示所有可使用的命令。

• engines
  指定运行的平台，如 Node.js 的某个版本、NPM 版本或浏览器。

• repository
  代码存放位置，如：

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

• dependencies
  指定项目运行需要依赖的模块，JSON 对象类型，每个对象成员分别由模块名和对应版本要求组成，表示依赖的模块和其版本范围。

  "dependencies": {
      "echarts": "4.2.1",
      "axios": "^0.19.0",
      "js-cookie": "~2.2.0",
      "sortablejs": "latest"
  }
  

  版本号限定分以下几种：

  • 指定版本号：如上例中的 echarts，只安装指定版本。
  • ^ + 指定版本号：如上例中的 axios，表示安装同一主版本号下的最新版本，即只能安装 0.x.x 版本，不能安装 1.x.x 版本。
  • ~ + 指定版本号：如上例中的 js-cookie，表示安装同一主版本号和次版本号下的最新版本，即只能安装 2.2.x 版本，不能安装 2.3.x 版本。
  • latest：安装最新版本。

• devDependencies
  指定项目开发需要依赖的模块，同 dependencies 一样也是一个JSON 对象类型，每个对象成员分别由模块名和对应版本要求组成，表示依赖的模块和其版本范围。版本号限定规则和 dependencies 一致。

• bugs
  问题跟踪系统地址或邮箱，npm bugs 时使用，如：

  "bugs": "https://github.com/..."
  

• gitHooks
@vue/cli-service 安装后会安装 yorkie，允许在 package.json 的 gitHooks 字段中方便地指定 Git Hook。

• lint-staged