package.json指南

package.json文件是許多基於Node.js生態系統的應用代碼庫中的關鍵元素。

如果您使用JavaScript,或者曾經與JavaScript項目,Node.js或前端項目進行過交互,那麼您肯定會遇到package.json文件。

那個有什麼用途?您應該了解什麼,可以使用它完成哪些有趣的事情?

package.json文件是您項目的清單。它可以做很多事情,完全不相關。例如,它是工具配置的中央存儲庫。這也是npmyarn存儲其安裝的軟件包的名稱和版本。

文件結構

這是一個示例package.json文件:

{

}

它是空的!沒有什麼要求應該有固定的要求package.json文件,用於應用程序。唯一的要求是,它必須遵循JSON格式,否則,嘗試以編程方式訪問其屬性的程序將無法讀取該格式。

如果您要構建要分發的Node.js程序包npm事情發生了根本性的變化,您必須具有一組可以幫助其他人使用它的屬性。我們將在以後看到更多有關此的內容。

這是另一個package.json:

{
  "name": "test-project"
}

它定義了一個name屬性,告訴應用程序或程序包的名稱,該屬性包含在該文件所在的同一文件夾中。

這是一個更為複雜的示例,我從示例Vue.js應用程序中提取了此示例:

{
  "name": "test-project",
  "version": "1.0.0",
  "description": "A Vue.js project",
  "main": "src/main.js",
  "private": true,
  "scripts": {
    "dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
    "start": "npm run dev",
    "unit": "jest --config test/unit/jest.conf.js --coverage",
    "test": "npm run unit",
    "lint": "eslint --ext .js,.vue src test/unit",
    "build": "node build/build.js"
  },
  "dependencies": {
    "vue": "^2.5.2"
  },
  "devDependencies": {
    "autoprefixer": "^7.1.2",
    "babel-core": "^6.22.1",
    "babel-eslint": "^8.2.1",
    "babel-helper-vue-jsx-merge-props": "^2.0.3",
    "babel-jest": "^21.0.2",
    "babel-loader": "^7.1.1",
    "babel-plugin-dynamic-import-node": "^1.2.0",
    "babel-plugin-syntax-jsx": "^6.18.0",
    "babel-plugin-transform-es2015-modules-commonjs": "^6.26.0",
    "babel-plugin-transform-runtime": "^6.22.0",
    "babel-plugin-transform-vue-jsx": "^3.5.0",
    "babel-preset-env": "^1.3.2",
    "babel-preset-stage-2": "^6.22.0",
    "chalk": "^2.0.1",
    "copy-webpack-plugin": "^4.0.1",
    "css-loader": "^0.28.0",
    "eslint": "^4.15.0",
    "eslint-config-airbnb-base": "^11.3.0",
    "eslint-friendly-formatter": "^3.0.0",
    "eslint-import-resolver-webpack": "^0.8.3",
    "eslint-loader": "^1.7.1",
    "eslint-plugin-import": "^2.7.0",
    "eslint-plugin-vue": "^4.0.0",
    "extract-text-webpack-plugin": "^3.0.0",
    "file-loader": "^1.1.4",
    "friendly-errors-webpack-plugin": "^1.6.1",
    "html-webpack-plugin": "^2.30.1",
    "jest": "^22.0.4",
    "jest-serializer-vue": "^0.3.0",
    "node-notifier": "^5.1.2",
    "optimize-css-assets-webpack-plugin": "^3.2.0",
    "ora": "^1.2.0",
    "portfinder": "^1.0.13",
    "postcss-import": "^11.0.0",
    "postcss-loader": "^2.0.8",
    "postcss-url": "^7.2.1",
    "rimraf": "^2.6.0",
    "semver": "^5.3.0",
    "shelljs": "^0.7.6",
    "uglifyjs-webpack-plugin": "^1.1.1",
    "url-loader": "^0.5.8",
    "vue-jest": "^1.0.2",
    "vue-loader": "^13.3.0",
    "vue-style-loader": "^3.0.1",
    "vue-template-compiler": "^2.5.2",
    "webpack": "^3.6.0",
    "webpack-bundle-analyzer": "^2.9.0",
    "webpack-dev-server": "^2.9.1",
    "webpack-merge": "^4.1.0"
  },
  "engines": {
    "node": ">= 6.0.0",
    "npm": ">= 3.0.0"
  },
  "browserslist": [
    "> 1%",
    "last 2 versions",
    "not ie <= 8"
  ]
}

很多這裡發生的事情:

  • name設置應用程序/程序包名稱
  • version指示當前版本
  • description是應用程序/程序包的簡要說明
  • main設置應用程序的入口點
  • private如果設置為true防止應用/軟件包被意外發佈到npm
  • scripts定義了一組可以運行的節點腳本
  • dependencies設置一個列表npm軟件包作為依賴安裝
  • devDependencies設置一個列表npm軟件包安裝為開發依賴項
  • engines設置此程序包/應用程序在哪個版本的Node上運行
  • browserslist用於告訴您要支持哪些瀏覽器(及其版本)

所有這些屬性都被其中一個使用npm或我們可以使用的其他工具。

屬性細目

本節描述了可以詳細使用的屬性。我指的是“軟件包”,但同樣的情況適用於您不用作軟件包的本地應用程序。

其中大多數屬性僅用於https://www.npmjs.com/,其他通過與您的代碼進行交互的腳本進行,例如npm或其他。

name

設置程序包名稱。

例子:

"name": "test-project"

名稱必須少於214個字符,不能包含空格,只能包含小寫字母,連字符(-)或下劃線(_)。

這是因為在發佈軟件包時npm,它會基於此屬性獲取自己的URL。

如果您在GitHub上公開發布了此軟件包,則此屬性的一個不錯的選擇就是GitHub存儲庫名稱。

author

列出軟件包作者名稱

例子:

{
  "author": "Flavio Copes <[email protected]> (https://flaviocopes.com)"
}

也可以使用以下格式:

{
  "author": {
    "name": "Flavio Copes",
    "email": "[email protected]",
    "url": "https://flaviocopes.com"
  }
}

contributors

除作者外,該項目可以有一個或多個貢獻者。此屬性是列出它們的數組。

例子:

{
  "contributors": [
    "Flavio Copes <[email protected]> (https://flaviocopes.com)"
  ]
}

也可以使用以下格式:

{
  "contributors": [
    {
      "name": "Flavio Copes",
      "email": "[email protected]",
      "url": "https://flaviocopes.com"
    }
  ]
}

bugs

鏈接到軟件包問題跟踪器,最有可能是GitHub問題頁面

例子:

{
  "bugs": "https://github.com/flaviocopes/package/issues"
}

homepage

設置程序包主頁

例子:

{
  "homepage": "https://flaviocopes.com/package"
}

version

指示軟件包的當前版本。

例子:

"version": "1.0.0"

此屬性遵循版本的語義版本(符號)表示法,這意味著版本始終以3個數字表示:x.x.x

第一個數字是主要版本,第二個數字是次要版本,第三個數字是補丁程序版本。

這些數字中有一個含義:僅修正錯誤的發行版是補丁發行版,引入向後兼容更改的發行版是次要發行版,主要發行版可能具有重大更改。

license

指示軟件包的許可證。

例子:

"license": "MIT"

keywords

此屬性包含與包的功能相關聯的關鍵字數組。

例子:

"keywords": [
  "email",
  "machine learning",
  "ai"
]

這可以幫助人們在瀏覽相似的軟件包或瀏覽類似的軟件包時找到您的軟件包https://www.npmjs.com/網站。

description

該屬性包含對軟件包的簡短描述

例子:

"description": "A package to work with strings"

如果您決定將軟件包發佈到npm這樣人們就可以了解包裝的內容。

repository

此屬性指定此程序包存儲庫所在的位置。

例子:

"repository": "github:flaviocopes/testing",

注意github字首。其他受歡迎的服務還包括:

"repository": "gitlab:flaviocopes/testing",
"repository": "bitbucket:flaviocopes/testing",

您可以顯式設置版本控制系統:

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

您可以使用不同的版本控制系統:

"repository": {
  "type": "svn",
  "url": "..."
}

main

設置包的入口點。

在應用程序中導入此程序包時,應用程序將在該位置搜索模塊導出。

例子:

"main": "src/main.js"

private

如果設置為true防止應用/軟件包被意外發佈到npm

例子:

"private": true

scripts

定義一組可以運行的節點腳本

例子:

"scripts": {
  "dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
  "start": "npm run dev",
  "unit": "jest --config test/unit/jest.conf.js --coverage",
  "test": "npm run unit",
  "lint": "eslint --ext .js,.vue src test/unit",
  "build": "node build/build.js"
}

這些腳本是命令行應用程序。您可以通過調用來運行它們npm run XXXX或者yarn XXXX, 在哪裡XXXX是命令名稱。例子:npm run dev

您可以為命令使用任何名稱,腳本可以執行任何您想要的操作。

dependencies

設置清單npm軟件包作為依賴項安裝。

使用npm或yarn安裝軟件包時:

npm install <PACKAGENAME>
yarn add <PACKAGENAME>

該軟件包將自動插入此列表中。

例子:

"dependencies": {
  "vue": "^2.5.2"
}

devDependencies

設置清單npm作為開發依賴項安裝的軟件包。

他們不同於dependencies因為它們只能安裝在開發機器上,而無需在生產環境中運行代碼。

使用npm或yarn安裝軟件包時:

npm install --dev <PACKAGENAME>
yarn add --dev <PACKAGENAME>

該軟件包將自動插入此列表中。

例子:

"devDependencies": {
  "autoprefixer": "^7.1.2",
  "babel-core": "^6.22.1"
}

engines

設置此程序包/應用程序可以處理哪些版本的Node.js和其他命令

例子:

"engines": {
  "node": ">= 6.0.0",
  "npm": ">= 3.0.0",
  "yarn": "^0.13.0"
}

browserslist

用於告訴您要支持哪些瀏覽器(及其版本)。 Babel,Autoprefixer和其他工具引用了它,僅將所需的polyfill和fallback添加到目標瀏覽器中。

例子:

"browserslist": [
  "> 1%",
  "last 2 versions",
  "not ie <= 8"
]

此配置表示您希望使用至少1%的使用率來支持所有瀏覽器的最後2個主要版本(從CanIUse.com統計信息),但IE8及更低版本除外。

看更多

特定於命令的屬性

package.json文件還可以託管特定於命令的配置,例如Babel,ESLint等。

每個都有特定的屬性,例如eslintConfigbabel和別的。這些是特定於命令的,您可以在相應的命令/項目文檔中找到如何使用它們。

套件版本

您已經在上面的描述中看到了類似以下的版本號:~3.0.0或者^0.13.0。它們是什麼意思,您還可以使用哪些其他版本說明符?

該符號指定您的軟件包從該依賴項接受哪些更新。

鑑於使用semver(語義版本控制),所有版本都有3位數字,第一個是主要發行版,第二個是次要發行版,第三個是補丁發行版,您具有以下規則:

  • ~:如果您寫~0.13.0,您只想更新補丁程序版本:0.13.1可以,但是0.14.0不是。
  • ^:如果您寫^0.13.0,您要更新補丁程序和次要版本:0.13.10.14.0等等。
  • *:如果您寫*,則表示您接受所有更新,包括主要版本升級。
  • >:您接受比您指定的版本更高的任何版本
  • >=:您接受等於或高於您指定的版本的任何版本
  • <=:您接受等於或低於您指定的版本的任何版本
  • <:您接受低於指定版本的任何版本

還有其他規則:

  • 無符號:您僅接受指定的特定版本
  • latest:您想使用可用的最新版本

並且您可以將上述大多數內容組合在範圍內,如下所示:1.0.0 || >=1.1.0 <1.2.0,以使用1.0.0或從1.1.0起但低於1.2.0的一個發行版。

免費下載我的Node.js手冊


更多節點教程: