引言

npm是前端開(kāi)發(fā)人員廣泛使用的包管理工具，項(xiàng)目中通過(guò)package.json來(lái)管理項(xiàng)目中所依賴的npm包的配置。package.json就是一個(gè)json文件，除了能夠描述項(xiàng)目的包依賴外，允許我們使用“語(yǔ)義化版本規(guī)則”指明你項(xiàng)目依賴包的版本，讓你的構(gòu)建更好地與其他開(kāi)發(fā)者分享，便于重復(fù)使用。

本文主要從最近的實(shí)踐出發(fā)，結(jié)合最新的npm和node的版本，介紹一下package.json中一些常見(jiàn)的配置以及如何寫(xiě)一個(gè)規(guī)范的package.json

package.json

package.json常用屬性

package.json環(huán)境相關(guān)屬性

package.json依賴相關(guān)屬性

package.json三方屬性

一、package.json

1. package.json簡(jiǎn)介

在nodejs項(xiàng)目中，package.json是管理其依賴的配置文件，通常我們?cè)诔跏蓟粋€(gè)nodejs項(xiàng)目的時(shí)候會(huì)通過(guò)：

npm init

然后在你的目錄下會(huì)生成3個(gè)目錄/文件， node_modules, package.json和 package.lock.json。其中package.json的內(nèi)容為：

{
    "name": "Your project name",
    "version": "1.0.0",
    "description": "Your project description",
    "main": "app.js",
    "scripts": {
        "test": "echo \"Error: no test specified\" && exit 1",
    },
    "author": "Author name",
    "license": "ISC",
    "dependencies": {
        "dependency1": "^1.4.0",
        "dependency2": "^1.5.2"
    }
}

上述可以看出，package.json中包含了項(xiàng)目本身的元數(shù)據(jù),以及項(xiàng)目的子依賴信息(比如dependicies等)。

2. package-lock.json

我們發(fā)現(xiàn)在npm init的時(shí)候，不僅生成了package.json文件，還生成了package-lock.json文件。那么為什么存在package.json的清空下，還需要生成package-lock.json文件呢。本質(zhì)上package-lock.json文件是為了鎖版本，在package.json中指定的子npm包比如：react: "^16.0.0"，在實(shí)際安裝中，只要高于react的版本都滿足package.json的要求。這樣就使得根據(jù)同一個(gè)package.json文件，兩次安裝的子依賴版本不能保證一致。

而package-lock文件如下所示，子依賴dependency1就詳細(xì)的指定了其版本。起到lock版本的作用。

{
    "name": "Your project name",
    "version": "1.0.0",
    "lockfileVersion": 1,
    "requires": true,
    "dependencies": {
        "dependency1": {
            "version": "1.4.0",
            "resolved": 
"https://registry.npmjs.org/dependency1/-/dependency1-1.4.0.tgz",
            "integrity": 
"sha512-a+UqTh4kgZg/SlGvfbzDHpgRu7AAQOmmqRHJnxhRZICKFUT91brVhNNt58CMWU9PsBbv3PDCZUHbVxuDiH2mtA=="
        },
        "dependency2": {
            "version": "1.5.2",
            "resolved": 
"https://registry.npmjs.org/dependency2/-/dependency2-1.5.2.tgz",
            "integrity": 
"sha512-WOn21V8AhyE1QqVfPIVxe3tupJacq1xGkPTB4iagT6o+P2cAgEOOwIxMftr4+ZCTI6d551ij9j61DFr0nsP2uQ=="
        }
    }
}

二、package.json常用屬性

本章來(lái)聊聊package.json中常用的配置屬性，形如name，version等屬性太過(guò)簡(jiǎn)單，不一一介紹。本章主要介紹一下script、bin和workspaces屬性。

1. script

在npm中使用script標(biāo)簽來(lái)定義腳本，每當(dāng)制定npm run的時(shí)候，就會(huì)自動(dòng)創(chuàng)建一個(gè)shell腳本，這里需要注意的是，npm run新建的這個(gè) Shell，會(huì)將本地目錄的node_modules/.bin子目錄加入PATH變量。

這意味著，當(dāng)前目錄的node_modules/.bin子目錄里面的所有腳本，都可以直接用腳本名調(diào)用，而不必加上路徑。比如，當(dāng)前項(xiàng)目的依賴?yán)锩嬗?esbuild，只要直接寫(xiě)esbuild xxx 就可以了。

{
  // ...
  "scripts": {
    "build": "esbuild index.js",
  }
}

{
  // ...
  "scripts": {
    "build": "./node_modules/.bin/esbuild index.js" 
  }
}

上面兩種寫(xiě)法是等價(jià)的。

2. bin

bin屬性用來(lái)將可執(zhí)行文件加載到全局環(huán)境中，指定了bin字段的npm包，一旦在全局安裝，就會(huì)被加載到全局環(huán)境中，可以通過(guò)別名來(lái)執(zhí)行該文件。

比如@bytepack/cli的npm包：

"bin": {
    "bytepack": "./bin/index.js"
 },

一旦在全局安裝了@bytepack/cli，就可以直接通過(guò)bytepack來(lái)執(zhí)行相應(yīng)的命令，比如

bytepack -v
//顯示1.11.0

如果非全局安裝，那么會(huì)自動(dòng)連接到項(xiàng)目的node_module/.bin目錄中。與前面介紹的script標(biāo)簽中所說(shuō)的一致，可以直接用別名來(lái)使用。

3. workspaces

在項(xiàng)目過(guò)大的時(shí)候，最近越來(lái)越流行monorepo。提到monorepo就繞不看workspaces，早期我們會(huì)用yarn workspaces，現(xiàn)在npm官方也支持了workspaces. workspaces解決了本地文件系統(tǒng)中如何在一個(gè)頂層root package下管理多個(gè)子packages的問(wèn)題，在workspaces聲明目錄下的package會(huì)軟鏈到最上層root package的node_modules中。

直接以官網(wǎng)的例子來(lái)說(shuō)明：

{
  "name": "my-project",
  "workspaces": [
    "packages/a"
  ]
}

在一個(gè)npm包名為my-project的npm包中，存在workspaces配置的目錄。

.
+-- package.json
+-- index.js
`-- packages
   +-- a
   |  `-- package.json

并且該最上層的名為my-project的root包，有packages/a子包。此時(shí)，我們?nèi)绻鹡pm install,那么在root package中node_modules中安裝的npm包a，指向的是本地的package/a.

.
+-- node_modules
|  `-- packages/a -> ../packages/a
+-- package-lock.json
+-- package.json
`-- packages
   +-- a
   |   `-- package.json

上述的

-- packages/a -> ../packages/a

指的就是從node_modules中a鏈接到本地npm包的軟鏈

三、package.json環(huán)境相關(guān)屬性

常見(jiàn)的環(huán)境，基本上分為瀏覽器browser和node環(huán)境兩大類，接下來(lái)我們來(lái)看看package.json中，跟環(huán)境相關(guān)的配置屬性。環(huán)境的定義可以簡(jiǎn)單理解如下：

• browser環(huán)境：比如存在一些只有在瀏覽器中才會(huì)存在的全局變量等，比如window，Document等
• node環(huán)境: npm包的源文件中存在只有在node環(huán)境中才會(huì)有的一些變量和內(nèi)置包，內(nèi)置函數(shù)等。

1 type

js的模塊化規(guī)范包含了commonjs、CMD、UMD、AMD和ES module等，最早先在node中支持的僅僅是commonjs字段，但是從node13.2.0開(kāi)始后，node正式支持了ES module規(guī)范，在package.json中可以通過(guò)type字段來(lái)聲明npm包遵循的模塊化規(guī)范。

//package.json
{
   name: "some package",
   type: "module"||"commonjs" 
}

需要注意的是：

• 不指定type的時(shí)候，type的默認(rèn)值是commonjs，不過(guò)建議npm包都指定一下type
• 當(dāng)type字段指定值為module則采用ESModule規(guī)范
• 當(dāng)type字段指定時(shí)，目錄下的所有.js后綴結(jié)尾的文件，都遵循type所指定的模塊化規(guī)范
• 除了type可以指定模塊化規(guī)范外，通過(guò)文件的后綴來(lái)指定文件所遵循的模塊化規(guī)范，以.mjs結(jié)尾的文件就是使用的ESModule規(guī)范，以.cjs結(jié)尾的遵循的是commonjs規(guī)范

2 main & module & browser

除了type外，package.json中還有main,module和browser 3個(gè)字段來(lái)定義npm包的入口文件。

• main : 定義了 npm 包的入口文件，browser 環(huán)境和 node 環(huán)境均可使用
• module : 定義 npm 包的 ESM 規(guī)范的入口文件，browser 環(huán)境和 node - 環(huán)境均可使用
• browser : 定義 npm 包在 browser 環(huán)境下的入口文件

我們來(lái)看一下這3個(gè)字段的使用場(chǎng)景，以及同時(shí)存在這3個(gè)字段時(shí)的優(yōu)先級(jí)。我們假設(shè)有一個(gè)npm包為demo1,

----- dist
   |-- index.browser.js
   |-- index.browser.mjs
   |-- index.js
   |-- index.mjs

其package.json中同時(shí)指定了main,module和browser這3個(gè)字段，

  "main": "dist/index.js",  // main 
  "module": "dist/index.mjs", // module
  // browser 可定義成和 main/module 字段一一對(duì)應(yīng)的映射對(duì)象，也可以直接定義為字符串
  "browser": {
    "./dist/index.js": "./dist/index.browser.js", // browser+cjs
    "./dist/index.mjs": "./dist/index.browser.mjs"  // browser+mjs
  },
  // "browser": "./dist/index.browser.js" // browser

默認(rèn)構(gòu)建和使用，比如我們?cè)陧?xiàng)目中引用這個(gè)npm包：

import demo from 'demo'

通過(guò)構(gòu)建工具構(gòu)建上述代碼后，模塊的加載循序?yàn)椋?/p>

browser+mjs > module > browser+cjs > main

這個(gè)加載順序是大部分構(gòu)建工具默認(rèn)的加載順序，比如webapck、esbuild等等?？梢酝ㄟ^(guò)相應(yīng)的配置修改這個(gè)加載順序，不過(guò)大部分場(chǎng)景，我們還是會(huì)遵循默認(rèn)的加載順序。

3 exports

如果在package.json中定義了exports字段，那么這個(gè)字段所定義的內(nèi)容就是該npm包的真實(shí)和全部的導(dǎo)出，優(yōu)先級(jí)會(huì)高于main和file等字段。

舉例來(lái)說(shuō)：

{
  "name": "pkg",
  "exports": {
    ".": "./main.mjs",
    "./foo": "./foo.js"
  }
}

import { something } from "pkg"; // from "pkg/main.mjs"

const { something } = require("pkg/foo"); // require("pkg/foo.js")

從上述的例子來(lái)看，exports可以定義不同path的導(dǎo)出。如果存在exports后，以前正常生效的file目錄到處會(huì)失效，比如require('pkg/package.json')，因?yàn)樵趀xports中沒(méi)有指定，就會(huì)報(bào)錯(cuò)。

exports還有一個(gè)最大的特點(diǎn)，就是條件引用，比如我們可以根據(jù)不同的引用方式或者模塊化類型，來(lái)指定npm包引用不同的入口文件。

// package.json
{ 
  "name":"pkg",
  "main": "./main-require.cjs",
  "exports": {
    "import": "./main-module.js",
    "require": "./main-require.cjs"
  },
  "type": "module"
}

上述的例子中，如果我們通過(guò)

const p = require('pkg')

引用的就是"./main-require.cjs"。

如果通過(guò)：

import p from 'pkg'

引用的就是"./main-module.js"

最后需要注意的是 ： 如果存在exports屬性，exports屬性不僅優(yōu)先級(jí)高于main，同時(shí)也高于module和browser字段。

四、package.json依賴相關(guān)屬性

package.json中跟依賴相關(guān)的配置屬性包含了dependencies、devDependencies、peerDependencies和peerDependenciesMeta等。

dependencies是項(xiàng)目的依賴，而devDependencies是開(kāi)發(fā)所需要的模塊，所以我們可以在開(kāi)發(fā)過(guò)程中需要的安裝上去，來(lái)提高我們的開(kāi)發(fā)效率。這里需要注意的時(shí)，在自己的項(xiàng)目中盡量的規(guī)范使用，形如webpack、babel等是開(kāi)發(fā)依賴，而不是項(xiàng)目本身的依賴，不要放在dependencies中。

dependencies除了dependencies和devDependencies，本文重點(diǎn)介紹的是peerDependencies和peerDependenciesMeta。

1 peerDependencies

peerDependencies是package.json中的依賴項(xiàng),可以解決核心庫(kù)被下載多次，以及統(tǒng)一核心庫(kù)版本的問(wèn)題。

//package/pkg
----- node_modules
   |-- npm-a -> 依賴了react,react-dom
   |-- npm-b -> 依賴了react,react-dom
   |-- index.js

比如上述的例子中如果子npm包a,b都以來(lái)了react和react-dom,此時(shí)如果我們?cè)谧觧pm包a,b的package.json中聲明了PeerDependicies后，相應(yīng)的依賴就不會(huì)重新安裝。

需要注意的有兩點(diǎn)：

• 對(duì)于子npm包a,在npm7中，如果單獨(dú)安裝子npm a,其peerDependicies中的包，會(huì)被安裝下來(lái)。但是npm7之前是不會(huì)的。
• 請(qǐng)規(guī)范和詳細(xì)的指定PeerDependicies的配置，筆者在看到有些react組件庫(kù)，不在PeerDependicies中指定react和react-dom，或者將react和react-dom放到了dependicies中，這兩種不規(guī)范的指定都會(huì)存在一些問(wèn)題。
• 其二，正確的指定PeerDependicies中npm包的版本，react-focus-lock@2.8.1,peerDependicies指定的是："react": "^16.8.0 || ^17.0.0 || ^18.0.0"，但實(shí)際上，這個(gè)react-focus-lock并不支持18.x的react

2 peerDependenciesMeta

看到“Meta”就有元數(shù)據(jù)的意思，這里的peerDependenciesMeta就是詳細(xì)修飾了peerDependicies，比如在react-redux這個(gè)npm包中的package.json中有這么一段：

 "peerDependencies": {
    "react": "^16.8.3 || ^17 || ^18"
  },
 "peerDependenciesMeta": {
    "react-dom": {
      "optional": true
    },
    "react-native": {
      "optional": true
    }
  }

這里指定了"react-dom","react-native"在peerDependenciesMeta中，且為可選項(xiàng)，因此如果項(xiàng)目中檢測(cè)沒(méi)有安裝"react-dom"和"react-native"都不會(huì)報(bào)錯(cuò)。

值得注意的是，通過(guò)peerDependenciesMeta我們確實(shí)是取消了限制，但是這里經(jīng)常存在非A即B的場(chǎng)景，比如上述例子中，我們需要的是“react-dom”和"react-native"需要安裝一個(gè)，但是實(shí)際上通過(guò)上述的聲明，我們實(shí)現(xiàn)不了這種提示。

五、package.json三方屬性

package.json中也存在很多三方屬性，比如tsc中使用的types、構(gòu)建工具中使用的sideEffects,git中使用的husky，eslint使用的eslintIgnore，這些擴(kuò)展的配置，針對(duì)特定的開(kāi)發(fā)工具是有意義的這里不一一舉例。

以上就是package.json依賴環(huán)境相關(guān)屬性詳解的詳細(xì)內(nèi)容，更多關(guān)于package.json依賴環(huán)境相關(guān)屬性的資料請(qǐng)關(guān)注腳本之家其它相關(guān)文章！

最新評(píng)論