package.json 详解

[vivipure]

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

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

[vivipure]

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

npx depcheck

[vivipure]

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

这个文件的好处：

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

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

[vivipure]

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

解决办法：

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

[vivipure]

可以使用 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

[vivipure]

npm 版本标识

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

标识	含义	举例	代码
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.*

[vivipure]

npm包的版本可以进行废弃

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

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

取消废弃

npm deprecate <package>@<version> ""

[vivipure]

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