package.json的所有配置項及其用法，你都熟悉麼

CoyPan發表於2018-12-25
PackageJSON

寫在前面

在前端開發中，npm已經是必不可少的工具了。使用npm，不可避免的就要和package.json打交道。平時package.json用得挺多，但是沒有認真看過官方文件。本文結合npm官方文件以及自己平時使用過程中的感悟，談一談package.json。官方文件在這裡。

初始化

使用npm init命令就可以初始化一個package.json檔案。在初始化的過程中，會叫使用者輸入name, version等等資訊，當然，你都可以忽略。一路點回車，就生成了下面這樣一個初始化的package.json。

{
  "name": "test", // 假如專案叫做test
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}
複製程式碼

上面的package.json包含了專案的名稱，版本號，描述，入口檔案，執行指令碼，作者，開源協議等。package.json的內容遠不止這些，下面將一一進行介紹。在開發業務專案和開發元件庫的時候，package.json是略有不一樣的。我會把我認為重要的配置項加黑標識出來。

詳細介紹

  • name: 這個很好理解，就是package的名稱。不過需要注意的是，name有長度限制(雖然一般都不會超)，而且name不能以 【點】 或者 【下劃線】開頭，name中不能有大寫字母。這個是每一個package必須的。在業務程式碼中，通過require(${name})就可以引入對應的程式包了。

  • version: package的版本。對於業務專案來說，這個往往不太重要，但是如果你要釋出自己的專案，這個就顯得十分重要了。name和version共同決定了唯一一份程式碼。npm是用[npm-semver來解析版本號的。我們一般見到的都是大版本.次要版本.小版本這種版本號，比如16.1.0。版本號的規則、含義其實蠻多的，可以參考這篇文章。

  • desription：包的描述。開發元件庫時必需，簡明的向庫的使用者介紹這個庫是幹嘛的。對於公司的業務專案，這個配置項一般無所謂。

  • keywords：關鍵詞。一個字串陣列，對這個npm包的介紹。元件庫必需，便於使用者在npm中搜尋。對於公司業務專案，這個配置一般無所謂。

  • homepage： 專案主頁。對於開發元件庫來說挺有用的。

  • bugs：開發者的聯絡方式，程式碼庫的issues地址等。如果程式碼使用者發現了bug，可以通過這個配置項找到提bug的地方。

  • license：開源協議。對於開源元件庫，這個十分重要。之前react還因為這事兒沒少被社群嫌棄。開源協議略微複雜，用阮一峰前輩的一張圖來說明一下吧。注：圖裡少了ISC, ISC和BSD差不多

img

  • author：專案的作者。可以為字串，物件。

  • contributors：專案的貢獻者。author的陣列。

  • main：程式碼入口。這個十分重要，特別是對於元件庫。當你想在node_modules中修改你使用的某個元件庫的程式碼時，首先在node_modules中找到這個元件庫，第一眼就是要看這個main，找到元件庫的入口檔案。在這個入口檔案中再去修改程式碼吧。

  • scripts：指定了執行指令碼命令的npm命令列縮寫。十分重要。

來看一個例子：

"scripts": {
    "dev": "NODE_ENV=dev webpack-dev-server --progress --hot --host 0.0.0.0 --port 8089",
    "test": "NODE_ENV=test webpack --config webpack.test.config.js --progress",
    "online": "NODE_ENV=production webpack --config webpack.online.config.js --progress",
    "build": "webpack",
    "node": "node server.js"
  },
複製程式碼

在命令列輸入：npm run dev , 對應的命令就會被執行。這裡有一個地方需要注意，當執行npm run xxx的時候，node_modules/.bin/目錄會在執行時被加入系統的PATH變數。上面的例子，當我們在命令列輸入：npm run build時，其實真正執行的命令是node_modules/.bin/webpack而不是webpack。所以，當你的webpack並未全域性安裝時，直接在命令列輸入：webpack是會報錯的。因為你的webapck是安裝在node_modules/.bin/下面的。

  • directories：對整個程式碼結構的描述。告訴程式碼包使用者可以在哪裡找到對應的檔案。

  • files：陣列。表示程式碼包下載安裝完成時包括的所有檔案。

  • repository：對於元件庫很有用。讓元件庫使用者找到你的程式碼庫地址。這個配置項會直接在元件庫的npm首頁生效。例子:

    "repository": {
    "type": "git",
    "url": "git+https://github.com/CoyPan/react-scroll-to-show-cb.git"
},
複製程式碼

  • config：用於新增命令列的環境變數。具體用法見這裡。

  • dependencies：專案的依賴。通過npm install --save安裝的包會出現在這裡。注意，不要把測試工具、程式碼轉換器或者打包工具等放在這裡。當你在命令列裡面使用npm install react --save時，react就會出現在dependencies。預設是安裝最新的版本。如果想安裝某個特定的版本，可以npm install react@15.6.2。以下的dependencies，格式都是合法的，

    "dependencies" : { 
    "foo" : "1.0.0 - 2.9999.9999",
    "bar" : ">=1.0.2 <2.1.2",
    "baz" : ">1.0.2 <=2.3.4",
    "boo" : "2.0.1",
    "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
    "asd" : "http://asdf.com/asdf.tar.gz",
    "til" : "~1.2",
    "elf" : "~1.2.3",
    "two" : "2.x",
    "thr" : "3.3.x",
    "lat" : "latest",
    "dyl" : "file:../dyl"
  }
複製程式碼

    我們常見的是下面這些：

    "dependencies": {
    "foo": "1.0.0", // 指定了就是1.0.0版本
    "bar": "~1.2.2", // 安裝版本號不低於1.2.2的1.2.x的最新版本，例如:1.2.3， 1.2.4等等。1.2.1 ，1.3.x 等就不行了
    "baz": "ˆ1.2.2", // 安裝版本號不低於1.2.2的1.x.x的最新版本，例如: 1.2.7，1.3.1，1.7.8等。1.2.1 ，2.0.0 等就不行了。注意，如果配置是^0.x.x，則和~0.x.x的效果一樣。				
    "lat": "latest"  // 安裝最新版本
}
複製程式碼

    dependencies 還可以像下面這樣配置：

    "dependencies": {
    "foo": "git+ssh://git@github.com:foo/foo.git#v1.0.1",
}
複製程式碼

    foo元件的地址為git+ssh://{foo程式碼庫的ssh地址}#v{foo的版本號}

    這樣的配置在下面這種場景十分有用：

    組內的許多專案都有同一個功能，把這個功能抽出來做成元件是很自然的想法。但是每個專案都有自己的程式碼庫，公司也沒有內部的npm庫，元件應該放在哪裡呢？可以專門為元件新建一個程式碼倉庫，將元件放在這裡開發、迭代。這樣，各個專案都可以引用該元件：只需要在dependencies中將元件配置成上述的形式。至於元件的版本，可以通過git tag來控制。

    dependencies還有其他的配置方式，具體在這裡檢視。

  • devDependencies：專案的依賴。通過npm run install --save-dev安裝的包會出現在這裡。主要是在開發過程中依賴的一些工具。用法與dependencies相似。

  • bundledDependencies：陣列，打包時的依賴。如果配置了bundledDependencies，在專案中執行 npm pack將專案打包時，最後生成的.tgz包中，會包含bundledDependencies中配置的依賴。bundledDependencies中的依賴必須在devDependencies或者dependencies中宣告過。

  • peerDependencies: 指定當前元件的依賴以其版本。如果元件使用者在專案中安裝了其他版本的同一依賴，會提示報錯。

  • engines：指定專案所依賴的node環境、npm版本等。

  • private：如果設為true，無法通過npm publish釋出程式碼。

  • bin：用來指定各個內部命令對應的可執行檔案的路徑。具體用法這裡不多講了。詳情可以點選這裡。

總結

本文涵蓋了package.json絕大部分的配置項。我的觀點是：如果是公司的業務專案，對於package.json，一般情況下，我覺得只需要關注好scripts，dependencies，devDependencies這三個地方就夠了。而對於開源的元件庫，則至少需要關注好上面標黑的幾個點。理解好重要配置的含義，提升開發效率，減少踩坑的概率。

寫在後面

本文結合官方文件以及自己平時工作中的體會，闡述了package.json這個配置檔案中各項的含義以及用法。符合預期。

相關文章