Analisis ringkas tentang atribut biasa package.json dalam projek nodejs

Artikel ini akan membawa anda melalui fail konfigurasi package.json dalam projek nod dan bercakap tentang beberapa sifat konfigurasi biasa, sifat berkaitan persekitaran, sifat berkaitan kebergantungan dan sifat pihak ketiga dalam pakej .json. Saya harap ia akan membantu Semua orang membantu!

npm ialah alat pengurusan pakej yang digunakan secara meluas oleh pembangun bahagian hadapan Dalam projek, package.json digunakan untuk mengurus konfigurasi pakej npm yang bergantung kepada projek pada. package.json ialah fail json Selain menerangkan kebergantungan pakej projek, ia juga membenarkan kami menggunakan "peraturan versi semantik" untuk menunjukkan versi pakej bergantung projek anda, membolehkan binaan anda dikongsi dengan lebih baik dengan pembangun lain untuk memudahkan. guna semula. Artikel ini terutamanya bermula daripada amalan terkini, digabungkan dengan versi npm dan nod terkini, untuk memperkenalkan beberapa konfigurasi biasa dalam package.json dan cara menulis pakej standard.json

---

1. pakej .json

1 Pengenalan kepada package.json

Dalam projek nodejs, package.json ialah konfigurasi yang menguruskannya dependencies Fail, biasanya apabila kami memulakan projek nodejs, kami akan lulus:

npm init

Kemudian 3 direktori/fail akan dijana dalam direktori anda, node_modules, package.json dan package.lock.json. Kandungan package.json ialah:

{
    "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"
    }
}

Seperti yang dapat dilihat daripada di atas, package.json mengandungi metadata projek itu sendiri, serta maklumat sub-pergantungan projek (seperti tanggungan, dsb.).

2. package-lock.json

Kami mendapati bahawa semasa npm init, bukan sahaja fail package.json telah dijana, tetapi juga fail package-lock.json. Jadi mengapa kita masih perlu menjana fail package-lock.json semasa mengosongkan package.json? Pada asasnya, fail package-lock.json adalah untuk mengunci versi Pakej sub-npm yang dinyatakan dalam package.json adalah seperti: react: "^16.0.0". bertindak balas, package.json memenuhi keperluan. Ini bermakna mengikut fail package.json yang sama, versi sub-dependensi yang dipasang dua kali tidak boleh dijamin konsisten.

Fail kunci pakej adalah seperti yang ditunjukkan di bawah, dan kebergantungan sub-kebergantungan1 menentukan versinya secara terperinci. Memainkan peranan versi kunci.

{
    "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=="
        }
    }
}

2. Atribut yang biasa digunakan bagi package.json

Bab ini akan membincangkan tentang atribut konfigurasi yang biasa digunakan dalam package.json seperti nama, versi dan sebagainya terlalu Mudah, jangan perkenalkan satu persatu. Bab ini terutamanya memperkenalkan sifat skrip, tong dan ruang kerja.

skrip 2.1

Gunakan teg skrip dalam npm untuk mentakrifkan skrip Setiap kali npm run ditentukan, shell akan dibuat secara automatik. Skrip, apa yang perlu diperhatikan di sini ialah Shell baharu yang dicipta oleh npm run akan menambah subdirektori node_modules/.bin direktori tempatan kepada pembolehubah PATH.

Ini bermakna semua skrip dalam subdirektori node_modules/.bin direktori semasa boleh dipanggil terus dengan nama skrip tanpa menambah laluan. Contohnya, jika kebergantungan projek semasa termasuk esbuild, tulis terus esbuild xxx.

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

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

Dua cara penulisan di atas adalah setara.

2.2 bin

Atribut bin digunakan untuk memuatkan fail boleh laku ke dalam persekitaran global Pakej npm dengan medan bin ditentukan . Sekali dalam Jika dipasang secara global, ia akan dimuatkan ke dalam persekitaran global dan fail boleh dilaksanakan melalui alias.

Contohnya, pakej npm @bytepack/cli:

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

Setelah @bytepack/cli dipasang secara global, anda boleh terus melaksanakan arahan yang sepadan melalui bytepack, seperti

bytepack -v
//显示1.11.0

Jika ia tidak dipasang secara global, ia akan disambungkan secara automatik ke direktori node_module/.bin projek. Selaras dengan apa yang dikatakan dalam teg skrip yang diperkenalkan sebelum ini, ia boleh digunakan secara langsung dengan alias.

2.3 ruang kerja

Apabila projek terlalu besar, monorepo telah menjadi semakin popular baru-baru ini. Apabila bercakap tentang monorepo, jangan lupa untuk melihat ruang kerja Pada masa awal, kami akan menggunakan ruang kerja benang Sekarang npm secara rasmi menyokong ruang kerja. Workspaces menyelesaikan masalah tentang cara mengurus berbilang subpakej di bawah pakej akar peringkat atas dalam sistem fail tempatan Pakej dalam direktori perisytiharan ruang kerja akan dipautkan lembut ke node_modules pakej akar peringkat atas.

Untuk menggambarkan secara langsung dengan contoh dari tapak web rasmi:

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

Dalam pakej npm bernama my-project, terdapat direktori yang dikonfigurasikan oleh ruang kerja.

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

Dan pakej akar peringkat atas bernama my-project mempunyai pakej/subpakej. Pada masa ini, jika kita memasang npm, maka pakej npm a yang dipasang dalam node_modules dalam pakej root menghala ke pakej/a setempat.

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

di atas

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

Ia merujuk kepada pautan lembut daripada node_modules ke pakej npm tempatan

三、package.json环境相关属性

    常见的环境，基本上分为浏览器browser和node环境两大类，接下来我们来看看package.json中，跟环境相关的配置属性。环境的定义可以简单理解如下：

• browser环境：比如存在一些只有在浏览器中才会存在的全局变量等，比如window，Document等
• node环境: npm包的源文件中存在只有在node环境中才会有的一些变量和内置包，内置函数等。

3.1 type

    js的模块化规范包含了commonjs、CMD、UMD、AMD和ES module等，最早先在node中支持的仅仅是commonjs字段，但是从node13.2.0开始后，node正式支持了ES module规范，在package.json中可以通过type字段来声明npm包遵循的模块化规范。

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

需要注意的是：

• 不指定type的时候，type的默认值是commonjs，不过建议npm包都指定一下type

• 当type字段指定值为module则采用ESModule规范

• 当type字段指定时，目录下的所有.js后缀结尾的文件，都遵循type所指定的模块化规范

• 除了type可以指定模块化规范外，通过文件的后缀来指定文件所遵循的模块化规范，以.mjs结尾的文件就是使用的ESModule规范，以.cjs结尾的遵循的是commonjs规范

3.2 main & module & browser

    除了type外，package.json中还有main,module和browser 3个字段来定义npm包的入口文件。

• main : 定义了 npm 包的入口文件，browser 环境和 node 环境均可使用
• module : 定义 npm 包的 ESM 规范的入口文件，browser 环境和 node - 环境均可使用
• browser : 定义 npm 包在 browser 环境下的入口文件

我们来看一下这3个字段的使用场景，以及同时存在这3个字段时的优先级。我们假设有一个npm包为demo1,

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

其package.json中同时指定了main,module和browser这3个字段，

  "main": "dist/index.js",  // main 
  "module": "dist/index.mjs", // module

  // browser 可定义成和 main/module 字段一一对应的映射对象，也可以直接定义为字符串
  "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

默认构建和使用，比如我们在项目中引用这个npm包：

import demo from 'demo'

通过构建工具构建上述代码后，模块的加载循序为：

browser+mjs > module > browser+cjs > main

这个加载顺序是大部分构建工具默认的加载顺序，比如webapck、esbuild等等。可以通过相应的配置修改这个加载顺序，不过大部分场景，我们还是会遵循默认的加载顺序。

3.3 exports

    如果在package.json中定义了exports字段，那么这个字段所定义的内容就是该npm包的真实和全部的导出，优先级会高于main和file等字段。

举例来说：

{
  "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")

从上述的例子来看，exports可以定义不同path的导出。如果存在exports后，以前正常生效的file目录到处会失效，比如require('pkg/package.json')，因为在exports中没有指定，就会报错。

    exports还有一个最大的特点，就是条件引用，比如我们可以根据不同的引用方式或者模块化类型，来指定npm包引用不同的入口文件。

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

上述的例子中，如果我们通过

const p = require('pkg')

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

如果通过：

import p from 'pkg'

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

最后需要注意的是 ：如果存在exports属性，exports属性不仅优先级高于main，同时也高于module和browser字段。

三、package.json依赖相关属性

    package.json中跟依赖相关的配置属性包含了dependencies、devDependencies、peerDependencies和peerDependenciesMeta等。

   dependencies是项目的依赖，而devDependencies是开发所需要的模块，所以我们可以在开发过程中需要的安装上去，来提高我们的开发效率。这里需要注意的时，在自己的项目中尽量的规范使用，形如webpack、babel等是开发依赖，而不是项目本身的依赖，不要放在dependencies中。

   dependencies除了dependencies和devDependencies，本文重点介绍的是peerDependencies和peerDependenciesMeta。

3.1 peerDependencies

peerDependencies是package.json中的依赖项,可以解决核心库被下载多次，以及统一核心库版本的问题。

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

比如上述的例子中如果子npm包a,b都以来了react和react-dom,此时如果我们在子npm包a,b的package.json中声明了PeerDependicies后，相应的依赖就不会重新安装。

需要注意的有两点：

• 对于子npm包a,在npm7中，如果单独安装子npm a,其peerDependicies中的包，会被安装下来。但是npm7之前是不会的。
• 请规范和详细的指定PeerDependicies的配置，笔者在看到有些react组件库，不在PeerDependicies中指定react和react-dom，或者将react和react-dom放到了dependicies中，这两种不规范的指定都会存在一些问题。
• 其二，正确的指定PeerDependicies中npm包的版本，react-focus-lock@2.8.1,peerDependicies指定的是："react": "^16.8.0 || ^17.0.0 || ^18.0.0"，但实际上，这个react-focus-lock并不支持18.x的react

3.2 peerDependenciesMeta

    看到“Meta”就有元数据的意思，这里的peerDependenciesMeta就是详细修饰了peerDependicies，比如在react-redux这个npm包中的package.json中有这么一段：

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

这里指定了"react-dom","react-native"在peerDependenciesMeta中，且为可选项，因此如果项目中检测没有安装"react-dom"和"react-native"都不会报错。

    值得注意的是，通过peerDependenciesMeta我们确实是取消了限制，但是这里经常存在非A即B的场景，比如上述例子中，我们需要的是“react-dom”和"react-native"需要安装一个，但是实际上通过上述的声明，我们实现不了这种提示。

四、package.json三方属性

    package.json中也存在很多三方属性，比如tsc中使用的types、构建工具中使用的sideEffects,git中使用的husky，eslint使用的eslintIgnore，这些扩展的配置，针对特定的开发工具是有意义的这里不一一举例。

更多node相关知识，请访问：nodejs 教程！

Atas ialah kandungan terperinci Analisis ringkas tentang atribut biasa package.json dalam projek nodejs. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!