文件 package.json 的說明文檔

文檔複製 yarnpkg 官方文檔,並非徹底複製,增長了一些內容和一些描述,做爲筆記存儲。你也能夠參考 npm documentation, std-pkg, clean-publish, package-json-validator, cosmiconfig, rchtml

歡迎來點 Stargithub.com/jaywcjlove/…node

重要字段

你的 package.json 中最重要的兩個字段是 nameversion,若是沒有它們,您的包將沒法安裝。 nameversion 字段一塊兒用於建立惟一ID。linux

name

{
  "name": "my-awesome-package"
}
複製代碼

這是您的 的名稱。 它在URL中使用,做爲參數命令行,以及 node_modules 中的目錄名。webpack

yarn add [包名]
# or
npm install [包名]
複製代碼
node_modules/[包名]
複製代碼
https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz
複製代碼

規則git

  • 必須小於或等於214個字符(包括 @scope/ for 範圍包)。
  • 不能以點(.)或下劃線(_)開頭。
  • 名稱中不得包含大寫字母。
  • 必須僅使用URL安全字符。

Tipsgithub

  • 不要使用和 Node.js 核心模塊相同的名字。
  • 不要在名字裏包含 js 或者 node 單詞。
  • 短小精悍,讓人看到名字就大概瞭解包的功能,記住它也會被用在 require() 調用裏。
  • 保證名字在 npm registry 裏是惟一的。

version

包的當前版本,嚴格遵循 Semantic Versioning 2.0.0 語義化版本規範。web

{
  "version": "1.0.0"
}
複製代碼

信息類字段

description

Description 是幫助使用者瞭解包的功能的字符串,包管理器也會把這個字符串做爲搜索關鍵詞。typescript

{
  "description": "個人包的概要簡短描述"
}
複製代碼

keywords

關鍵字是一個字符串數組,當在包管理器裏搜索包時頗有用。npm

{
  "keywords": ["short", "relevant", "keywords", "for", "searching"]
}
複製代碼

license

全部包都應該指定許可證,以便讓用戶瞭解他們是在什麼受權下使用此包,以及此包還有哪些附加限制。json

{
  "license": "MIT",
  "license": "(MIT or GPL-3.0)",
  "license": "SEE LICENSE IN LICENSE_FILENAME.txt",
  "license": "UNLICENSED"
}
複製代碼

鼓勵使用開源 (OSI-approved) 許可證,除非你有特別的緣由不用它。 若是你開發的包是你工做的一部分,最好和公司討論後再作決定。

license字段必須是如下之一:

  • 若是你使用標準的許可證,須要一個有效地 SPDX 許可證標識
  • 若是你用多種標準許可證,須要有效的 SPDX 許可證表達式2.0語法表達式
  • 若是你使用非標準的許可證,一個 SEE LICENSE IN <文件名> 字符串指向你的包裏頂級目錄的一個 <文件名>。
  • 若是你不想在任何條款下受權其餘人使用你的私有或未公開的包,一個 UNLICENSED 字符串。

連接類字段

各類指向項目文檔、issues 上報,以及代碼託管網站的連接字段。

homepage

是包的項目主頁或者文檔首頁。

{
  "homepage": "https://your-package.org"
}
複製代碼

bugs

問題反饋系統的 URL,或者是 email 地址之類的連接。用戶經過該途徑向你反饋問題。

{
  "bugs": "https://github.com/user/repo/issues"
}
複製代碼

repository

是代碼託管的位置。

{
  "repository": { "type": "git", "url": "https://github.com/user/repo.git" },
  "repository": "github:user/repo",
  "repository": "gitlab:user/repo",
  "repository": "bitbucket:user/repo",
  "repository": "gist:a1b2c3d4e5f"
}
複製代碼

The repository is the location where the actual code for your package lives.

項目維護類字段

項目的維護者。

author

做者信息,一我的。

{
  "author": { "name": "Your Name", "email": "you@example.com", "url": "http://your-website.com" },
  "author": "Your Name <you@example.com> (http://your-website.com)"
}
複製代碼

contributors

貢獻者信息,可能不少人。

{
  "contributors": [
    { "name": "Your Friend", "email": "friend@example.com", "url": "http://friends-website.com" }
    { "name": "Other Friend", "email": "other@example.com", "url": "http://other-website.com" }
  ],
  "contributors": [
    "Your Friend <friend@example.com> (http://friends-website.com)",
    "Other Friend <other@example.com> (http://other-website.com)"
  ]
}
複製代碼

文件類信息

指定包含在項目中的文件,以及項目的入口文件。

files

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}
複製代碼

項目包含的文件,能夠是單獨的文件、整個文件夾,或者通配符匹配到的文件。

main

項目的入口文件。

{
  "main": "filename.js"
}
複製代碼

bin

隨着項目一塊兒被安裝的可執行文件。

{
  "bin": "bin.js",
  "bin": {
    "命令名稱": "bin/命令路徑/命令名稱.js",
    "other-command": "bin/other-command"
  }
}
複製代碼

man

項目的入口文件。

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}
複製代碼

directories

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}
複製代碼

當你的包安裝時,你能夠指定確切的位置來放二進制文件、man pages、文檔、例子等。

types

這是一個只在 TypeScript 中生效的字段,若是您的包有一個 main.js 文件,您還須要在 package.json 文件中指明主聲明文件。 將 types 屬性設置爲指向 bundled 的聲明文件。 例如:

{
  "types": "./lib/main.d.ts",
}
複製代碼

若是您的主聲明文件名爲 index.d.ts 而且位於包的根目錄(index.js旁邊),則不須要標記 types 屬性,建議這樣作。

打包包字段

module

pkg.module 將指向具備 ES2015 模塊語法的模塊,但僅指向目標環境支持的語法功能。 完整的描述在這裏

支持:rollup, webpack

browser

字段由模塊做者提供,做爲 JavaScript 包或組件工具的提示,用於打包模塊以供客戶端使用。 提案就在這裏

esnext

完整的提案在這裏。 簡短說明:

  • esnext:ES模塊中使用階段4功能(或更舊版本)的源代碼,未編譯。
  • main:指向一個CommonJS模塊(或UMD模塊),其 JavaScriptNode.js 當前能夠處理的同樣現代。
  • 大多數 module 用例應該能夠經過 esnext 處理。
  • browser 能夠經過 esnext 的擴展版原本處理
{
  "main": "main.js",
  "esnext": {
    "main": "main-esnext.js",
    "browser": "browser-specific-main-esnext.js"
  }
}
複製代碼

另請參閱:Delivering untranspiled source code via npm

任務類字段

包裏還能夠包含一些可執行腳本或者其餘配置信息。

scripts

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}
複製代碼

腳本是定義自動化開發相關任務的好方法,好比使用一些簡單的構建過程或開發工具。 在 scripts 字段裏定義的腳本,能夠經過 yarn run <script> 命令來執行。 例如,上述 build-project 腳本能夠經過 yarn run build-project 調用,並執行 node build-project.js

有一些特殊的腳本名稱。 若是定義了 preinstall 腳本,它會在包安裝前被調用。 出於兼容性考慮,installpostinstallprepublish 腳本會在包完成安裝後被調用。

start 腳本的默認值爲 node server.js

參考文檔:npm docs

特定的 scripts

對於如下腳本,npm 支持 package.json 文件的 scripts 默認命令字段:

  • prepublish: 在打包併發布包以前運行,以及在沒有任何參數的本地 npm 安裝以前運行。 (見下文)
  • prepare: 在打包和發佈包以前運行,在沒有任何參數的本地 npm install 上運行,以及安裝 git 依賴項時(見下文)。 這是在 preublish 以後運行,可是在 preublishOnly 以前運行。
  • prepublishOnly: 在包準備和打包以前運行,僅限於npm發佈。 (見下文。)
  • prepack: 在打包 tarball 以前運行(在 npm packnpm publish,以及安裝 git 依賴項時)
  • postpack: 在生成 tarball 以後運行並移動到其最終目標。
  • publish, postpublish: 在包發佈後運行。
  • preinstall: 在安裝軟件包以前運行。
  • install, postinstall: 安裝包後運行。
  • preuninstall, uninstall: 在卸載軟件包以前運行。
  • postuninstall: 在卸載軟件包以後運行。
  • preversion: 在改變包版本以前運行。
  • version: 改變包版本後運行,但提交以前。
  • postversion: 改變包版本後運行,而後提交。
  • pretest, test, posttest: 由 npm test 命令運行。
  • prestop, stop, poststop: 由 npm stop 命令運行。
  • prestart, start, poststart: 由 npm start 命令運行。
  • prerestart, restart, postrestart: 由 npm restart 命令運行。 注意:若是沒有提供重啓腳本,npm restart 將運行 stopstart 腳本。
  • preshrinkwrap, shrinkwrap, postshrinkwrap: 由 npm shrinkwrap 命令運行。

參考文檔:npm docs.

config

{
  "config": {
    "port": "8080"
  }
}
複製代碼

配置你的腳本的選項或參數。

依賴描述類字段

你的包極可能依賴其餘包。你能夠在你的 package.json 文件裏指定那些依賴。

dependencies

這些是你的包的開發版和發佈版都須要的依賴。

{
  "dependencies": {
    "package-1": "^3.1.4",
    "package-2": "file:./path/to/dir"
  }
}
複製代碼

你能夠指定一個確切的版本、一個最小的版本 (好比 >=) 或者一個版本範圍 (好比 >= ... <)。
包也能夠指向本地的一個目錄文件夾。

devDependencies

這些是隻在你的包開發期間須要,可是生產環境不會被安裝的包。

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}
複製代碼

peerDependencies

平行依賴容許你說明你的包和其餘包版本的兼容性。

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}
複製代碼

optionalDependencies

可選依賴能夠用於你的包,但不是必需的。若是可選包沒有找到,安裝還能夠繼續。

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}
複製代碼

bundledDependencies

打包依賴是發佈你的包時將會一塊兒打包的一個包名數組。

{
  "bundledDependencies": [
    "package-4"
  ]
}
複製代碼

系統

你能夠提供和你的包關聯的系統級的信息,好比操做系統兼容性之類。

engines

指定使用你的包客戶必須使用的版本,這將檢查 process.versions 以及當前 yarn 版本。

{
  "engines": {
    "node": ">=4.4.7 <7.0.0",
    "zlib": "^1.2.8",
    "yarn": "^0.14.0"
  }
}
複製代碼

此檢查遵照正常的 semver 規則,但有一個例外。 它容許預發佈版本匹配未明確指定預發佈的 semver。 例如,1.4.0-rc.0 匹配 >=1.3.0,但它與典型的 semver 檢查不匹配。

os

此選項指定你的包的操做系統兼容性,它會檢查 process.platform

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}
複製代碼

cpu

使用這個選項指定你的包將只能在某些 CPU 體系架構上運行,這會檢查 process.arch

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}
複製代碼

發佈

private

{
  "private": true
}
複製代碼

若是你不想你的包發佈到包管理器(npm 或者 私有包管理),設置爲 true

publishConfig

這些配置值將在你的包發佈時使用。好比,你能夠給包打標籤。

{
  "publishConfig": {
    "registry": "https://registry.npm.taobao.org"
  }
}
複製代碼

這是一組將在發佈時使用的配置值。 若是要設置標記,註冊表或訪問權限,則特別方便,以便確保給定的包未標記爲 latest,發佈到全局公共 registry 或默認狀況下,做用域模塊(@scoped)是私有的。

能夠覆蓋任何配置值,但只有 tagregistryaccess 可能對於發佈而言很重要,npm-config

Yarn

flat

若是你的包只容許給定依賴的一個版本,你想強制和命令行上 yarn install --flat 相同的行爲,把這個值設爲 true

{
  "flat": true
}
複製代碼

請注意,若是你的 package.json 包含 "flat": true 而且其它包依賴你的包 (好比你在構建一個庫,而不是應用), 其它那些包也須要在它們的 package.json 加上 "flat": true,或者在命令行上用 yarn install --flat 安裝。

resolutions

{
  "resolutions": {
    "transitive-package-1": "0.0.29",
    "transitive-package-2": "file:./local-forks/transitive-package-2",
    "dependencies-package-1/transitive-package-3": "^2.1.1"
  }
}
複製代碼

容許您覆蓋特定嵌套依賴項的版本。 有關完整規範,請參見選擇性版本解析 RFC

注意,yarn install --flat 命令將會自動在 package.json 文件里加入 resolutions 字段。

相關文章
相關標籤/搜索