當(dāng)我們創(chuàng)建一個 Node 項目時， 需要創(chuàng)建一個 package.json 文件，描述這個項目所需要的各種模塊，以及項目的配置信息（比如名稱、版本、許可證等元數(shù)據(jù)）。

你可以在命令行使用 npm help package.json 命令，將跳轉(zhuǎn)到頁面，查看這些字段如何使用。下面將根據(jù)該文檔，進行整理。

字段信息

一般，開始一個項目時，我們會在命令行使用 npm init 命令生成 package.json 文件。

以下是 package.json 的一些字段信息：

name 項目名

{
  "name": "node"
}

version 描述項目的當(dāng)前版本號

{
  "version": "0.1.0"
}

description 項目的描述

{
  "description": "My package"
}

main 指定項目的主入口文件

{
  "main": "index.js"
}

author 項目作者信息，貢獻者。它可以有兩種寫法。email 和 url 是可選的。

// 方式一：
{
  "name" : "lio-zero",
  "email" : "licroning@163.com",
  "url" : "http://www.lxweimin.com/u/3f644e66afa3"
}

// 方式二：
{
  "author": "lio-zero <licroning@163.com> (http://www.lxweimin.com/u/3f644e66afa3)"
}

keywords 使用相關(guān)關(guān)鍵字描述項目

{
  "keywords": ["admin", "node", "node"]
}

license 許可證（告訴用戶可以做什么和不能做什么，常見：MIT、BSD-3-Clause）

{
  "keywords": "MIT"
}

scripts 指定運行腳本命令的 npm 命令行縮寫，比如 start 指定了運行 npm run start 時，所要執(zhí)行的命令。

{
  "scripts": {
    "start": "node ./bin/xxx"
  }
}

repository 字段用于指定代碼存放的位置。

{
  "repository": {
    "type": "git",
    "url": "這里寫上項目在 github 上的地址"
  }
}

您也可以添加 -y 標(biāo)志來生成默認的 package.json 文件：

{
  "name": "demo",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "keywords": [],
  "author": "",
  "license": "ISC"
}

使用 npm init -y 默認生成的 package.json 文件會少一個 repository 字段，需要的話可以手動添加上去。

接下來我們將在這基礎(chǔ)上介紹一些其他字段，他們都是可選的，也會在您使用某些 npm 命令時自動生成。

依賴

dependencies 字段指定了生產(chǎn)環(huán)境項目的依賴。當(dāng)你添加生產(chǎn)環(huán)境依賴時，他會自動生成，如：npm i express

{
  "dependencies": {
    "express": "^4.17.1"
  }
}

devDependencies 字段指定了開發(fā)環(huán)境項目的依賴。當(dāng)你添加生產(chǎn)環(huán)境依賴時，他會自動生成，如：npm i eslint -D

{
  "devDependencies": {
    "eslint": "^6.7.2"
  }
}

peerDependencies 兼容性依賴。如果你的包是插件，適合這種方式。

{
  "peerDependencies": {
    "tea": "2.x"
  },
}

optionalDependencies 如果你想在某些依賴即使沒有找到，或則安裝失敗的情況下，npm 都繼續(xù)執(zhí)行。那么這些依賴適合放在這里。

{
  "optionalDependencies": {},
}

bundledDependencies 發(fā)布包時捆綁的包名數(shù)組

{
   "bundledDependencies": ["renderized", "super-streams"]
}

配置

config 字段中的鍵作為 env 環(huán)境變量公開給腳本。

{
  "name": "node",
  "config": {
    "foo": "hello"
  }
}

你可以在應(yīng)用程序中使用 config 字段，當(dāng)用戶執(zhí)行 npm run start 命令時，這個腳本就可以得到值。

console.log(process.env.npm_package_config_foo)

你可以使用下面命令改變這個值。

$ npm config set node:foo hi

lint-staged

在代碼提交之前，進行代碼規(guī)則檢查能夠確保進入 git 庫的代碼都是符合代碼規(guī)則的。但是整個項目上運行 lint 速度會很慢，lint-staged 能夠讓 lint 只檢測暫存區(qū)的文件，所以速度很快。

安裝與配置

husky 和 lint-staged

$ npm i husky lint-staged -D

package.json 中配置：

{
  "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  "lint-staged": {
    "*.js": "eslint --fix"
  }
}

git commit 時觸發(fā) pre-commit 鉤子，運行 lint-staged 命令，對 *.js 執(zhí)行 eslint 命令。eslint 要提前配置好。

其他

homepage 項目首頁的網(wǎng)址。

{
  "homepage": "http://www.lxweimin.com/u/3f644e66afa3"
}

bugs 項目的問題追蹤系統(tǒng)的 URL 或郵箱地址，這些對遇到軟件包問題的人很有幫助。

{
  "bugs": { 
    "url" :"http://github.com/owner/project/issues",
    "email" :"project@hostname.com"
  }
}

bin 很多的包都會有執(zhí)行文件需要安裝到 PATH 中去。這個字段對應(yīng)的是一個 Map，每個元素對應(yīng)一個{ 命令名：文件名 }。這些可執(zhí)行文件的頭部需要加上 #!/usr/bin/env node。

{ 
  "bin": { 
    "npm": "./cli.js",
    "command": "./bin/command"
  } 
}

private 是一個布爾值。如果 private 為 true，可以保證包不會被發(fā)布到 npm。這可以防止私有 repositories 不小心被發(fā)布出去。

preferGlobal 是一個布爾值。如果你的包是個命令行應(yīng)用程序，需要全局安裝，就可以設(shè)為 true。

{
  "private": true,
  "preferGlobal": true
}

browserslist 指定項目所支持的瀏覽器版本。

{
  "browserslist": [
    "last 3 Chrome versions",
    "last 3 Firefox versions",
    "Safari >= 10",
    "Explorer >= 11",
  ]
}

engines 字段指明了該項目運行的平臺，比如 Node 的某個版本或者瀏覽器，也可以指定適用的 npm 版本。

{
  "engines": {
    "node": ">= 12.16.2",
    "npm": ">= 6.14.8"
  },
}

man 用來指定當(dāng)前項目的 man 文檔的位置。

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

style 指定供瀏覽器使用時，樣式文件所在的位置。樣式文件打包工具 parcelify，通過它知道樣式文件的打包位置。

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

cpu 指定 CPU 型號。

{
  "cpu" : [ "x64", "ia32" ],
  "cpu" : [ "!arm","!mips" ]
}

os 指定項目可以在什么操作系統(tǒng)上運行。

{
  "os" : [ "darwin","linux" ],
}

files 當(dāng)你發(fā)布項目時，具體哪些文件會發(fā)布上去。如果需要把某些文件不包含在項目中，添加一個 .npmignore 文件。這個文件和 gitignore 類似。

{
  "files": [
    "src",
    "dist/*.js",
    "types/*.d.ts"
  ],
}

publishConfig 是一個布爾值。如果你的包是個命令行應(yīng)用程序，需要全局安裝，就可以設(shè)為 true。

engineStrick 是一個布爾值。如果你肯定你的程序只能在制定的 engine 上運行，設(shè)置為 true。

還有一些特殊的字段，比如 prettier、unpkg、babel、jest 等，他們配合工具使用。

根據(jù) package.json 內(nèi)容自動生成 README.md 文件

對于任何開源項目來說，最重要的文檔就是 README。

這里介紹一個好用的工具 readme-md-generator，它將根據(jù) package.json 文件內(nèi)容自動生成漂亮 README文件

readme-md-generator 能夠讀取您的環(huán)境（package.json，git 配置等），創(chuàng)建項目的 README 文件。

以下是該模式提供的一個示例演示：

使用示例

基本配置

確保已安裝 npx（自 npm 以來默認 npx 5.2.0)

只需在項目根部運行以下命令并回答問題：

$ npx readme-md-generator

或使用 -y 標(biāo)志默認生成：

$ npx readme-md-generator -y

假設(shè)我們有如下配置：

{
  "name": "vue3",
  "version": "0.1.0",
  "private": true,
  "description": "vue3-demo",
  "author": "lio-zero <licroning@163.com>",
  "license": "MIT",
  "engines": {
    "node": ">= 12.16.2",
    "npm": ">= 6.14.8"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/lio-zero/vue3.git"
  },
  "homepage": "https://github.com/lio-zero/vue3.git#readme",
  "keywords": [
    "vue3",
    "cli"
  ],
  "scripts": {},
  "dependencies": {},
  "devDependencies": {}
}

效果如下：

生成 README.md

詳細內(nèi)容可以查閱文檔，例如可以單獨定制模板等。

更多資料

• package.json
• What's what? - Package.json cheatsheet!