package.json 文件结构详解

Question

package.json 作为 Node.js 包管理的配置文件，平时使用的频率太高了。但是对于其中有些字段的含义一直没有进行系统的学习。因此特意记录下 各个字段的意义和功能，参考文档： https://docs.npmjs.com/cli/v8/configuring-npm/package-json

name

应用名/包名。可以在前面使用 @xx/xx ​，标识 scope

version

版本号，可以参考 #10 (comment)

description

描述

keywords

关键词数组，用于 搜索

homepage

包首页，文档或者 github

bugs

一般可以 issue 地址， npm bug 可以打开该地址

license

许可协议

author

作者信息

files

包所包含的文件

bin

声明后，用户下载时在 bin 目录会增加一个 对应的 可执行 shell，对应的 js 需要加上 shebang

 "bin": {
    "cli": "./cli.js"
  }

// cli.js

#!/usr/bin/env node

scripts

可以用来定义命令，用来 npm run 进行使用。除了用户自定义，也包含生命周期。

我在使用 husky 时就会使用 prepare ，在每次下载时，执行 prepare 对应的脚本

总共有 ： prepare, prepublish, prepublishOnly, prepack, postpack

dependencies

• dependenices 安装时需要的依赖，
• devDependencies 开发时需要的依赖，例如 babel, webpack
• peerDependencies 要使用我这个包时，必须安装这个里面声明的包，一般库会使用。例如 Vue 的组件，需要在这个字段声明 Vue

os

支持的系统

cpu

支持的 CPU

workspace

monorepo 设置

type

type: 'module`

标识是 esm 还是 commonjs

main

main 是 npm package 的入口文件，当我们使用 CommonJS 导入包时，实际上导入的是 main 所指向的文件

// package.json 
{
    "name": "dep",
    "main": "./dist/index.js"
}

const dep = require('dep')
// 等同于
const dep = require('dep/dist/index.js')

module

moduele 是 ESM 导入时的寻找字段，若没有则引入 main 字段。所以一般库 CommonJS 放在 main, ESM 放在 module 字段

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

exports

exports 描述了子目录的访问路径，如果定义了 exports ,那么不在 exports 的模块，用路径也无法访问。

{
  name: 'midash',
  main: './index.js',
  exports: {
    '.': './dist/index.js',
    'es': './dist/es/index.js'
  }
}

engines

engines 指定了当前项目所需要的环境，例如声明 node 最小版本，如果本地环境与版本不匹配，则会进行报错

"engines": {
    "node": ">=14.0.0"
}

browser

在浏览器使用时，标识使用哪个文件

---

可以使用 depcheck 检查当前项目的依赖是否被使用

npx depcheck

---

package-lock.json 这个文件是安装依赖时自动生成的文件。

这个文件的好处：

1. 描述依赖关系树的单一表示，以保证团队成员、部署和持续集成安装完全相同的依赖关系。
2. 通过允许 npm 跳过以前安装的包的重复元数据解析来优化安装过程。
3. 从 npm v7 开始，lockfiles 包含足够的信息来获得包树，减少了读取 package.json 文件的需要，并允许显着提高性能。

可以使用 npm ci 来替代 npm i , 确保安装依赖的一致性

---

如果项目开发不严格，开发人员可能会引用未在 package.json 中定义的依赖，也就是 幽灵依赖 . 在第三方库引用了自身的依赖，导致即使项目未声明依赖也能正常使用。但是仍然存在安全隐患，例如后续依赖升级导致项目不能运行。

解决办法：

1. 可以使用 depeck 进行检查
2. 使用 pnpm 进行依赖管理，pnpm 将三方库的依赖硬链接到其他目录，只允许第三方库使用，项目无法直接使用。

---

可以使用 npm version [patch|minor|major] 命令增减版本号

1. npm version patch 小版本递增 0.0.1 -> 0.0.2
2. npm verison minor 中版本递增 0.0.2 -> 0.1.0
3. npm version major 大版本递增 0.1.0 -> 1.0.0

查考： https://semver.org/

major 大版本更新，功能 breaking change

minor 新增了向后兼容的功能

patch 修复向后兼容的缺陷

当执行 npm i 是默认的版本号是 ^ +最新版本, 我们可以通过在依赖指定版本进行下载

npm i dep@x.xx.xx

当 package-lock.json 不符合 package.json 的范围时，重新下载时会更新 package-lock.json

---

npm 版本标识

https://docs.npmjs.com/cli/v7/configuring-npm/package-json

标识	含义	举例	代码
version	指定版本	1.1.0: 1.1.0	npm i dep@1.1.0
～version	兼容 patch 版本	～1.1.0: 1.1.0<= version < 1.2.0	npm i dep@~1.1.0
^version	兼容 minor 版本	^1.1.0: 1.1.0<= version < 2.0.0	npm i dep@^1.1.0
>version	大于指定版本	> 1.1.0: 1.1.0 < version	npm i dep@>1.1.0
>=version	大于等于指定版本	>=1.1.0: 1.1.0 <= version	npm i dep@>=1.1.0
1.2.x	1.2.* 版本的小版本	> 1.2.*: 1.2.0,1.2.1,.. 1.3.0	npm i dep@1.2.*

---

npm 包的版本可以进行废弃

npm deprecate <package>@<version> <msg>

注意： 包和版本用@进行连接，如果存在空格，就会让整个仓库废弃

取消废弃

npm deprecate <package>@<version> ""

npx 的原理

npx 会检查 node_modules/.bin 目录和环境变量，调用相关命令。如果相关依赖没有下载的话，会下载到一个临时目录，不会影响到当前目录，也不会下载到全局。

npm package 可以在 package.json 中指定 bin 属性，定义命令的名称 和具体的 文件，一般是带有 shebang 的 nodejs 脚本。npm 在下载时，如果是 windows 平台，则会生成 .ps1 和 .cmd 文件，linux 和 mac 则会使用源文件。

npm init

npm init <package-spec> (same as `npx <package-spec>`)
npm init <@scope> (same as `npx <@scope>/create`)

aliases: create, innit

npm init 用于项目初始化，加-y 参数可以生成一份默认的 package.json，npm init 运行时，会用 npm exec 执行 create- 这个 npm package 的 bin 命令

npm init foo -> npm exec create-foo
npm init @usr/foo -> npm exec @usr/create-foo