关于 package.json 你了解多少?-每日运维

作为一个前端,相信大家对package.json这个文件想必并不陌生,它存在于每一个工程化前端的项目中,位于项目的根目录。它包含项目的一些配置信息,如项目名称、版本、作者等,这些信息对于项目的管理和维护非常重要。本篇文章将为大家详细介绍package.json中的字段的含义以及用法。
这里将这些字段分为四部分逐一介绍,分别是描述信息,脚本配置,依赖配置,发布配置,构建工具配置,文件配置

描述信息

name (名称)

项目的名字,如果你的项目是作为一个包发布到 npm 上的话那么它是必须要有的,而且是唯一的

"name":"ikun"

version (版本)

项目的版本,同样的如果要发布到 npm 上它也是必须的,它和 name 字段组合则可以唯一确定一个项目,如果作为一个包发布,你每一次更新这个包都要提升一下它的版本。version 遵循以下语义控制

比如项目版本号如下

"vue":"1.2.3"

1 代表主版本号 Major,通常在对项目进行重大更新的时候与以往版本不兼容的情况下才会更新,如 Vue2 到 Vue3
2 代表次版本号 Minor,引入了新的功能但是能向下兼容的时候会更新此版本号
3 代表修订版本号 Patch,修复优化了项目的一些问题的时候会更新此版本号

当然除了上面的版本号,还有如

"vue":"1.2.3-xxx"

这种形式的版本号,其中 xxx 有三种阅约定俗称的命名方式分别为 alpha（阿尔法版）,beta（贝塔版）,rc

alpha

通常表示早期的开发阶段，可能存在许多未解决的问题，不适合生产环境使用。如1.2.3-alpha.1表示1.2.3内测的第一个版本

beat

表示项目已经相对稳定，但仍在测试中，可能存在一些问题。开发者可以邀请用户参与测试和反馈问题,如1.2.3-beat.1表示1.2.3灰度测试的第一个版本

rc
候选版本，通常用于最终测试。如果没有发现重大问题，候选版本可能会成为正式发布版。如1.2.3-rc.1表示1.2.3预览的第一个版本

根据上面的描述相比大家已经猜到了它们的版本大小顺序了

1.2.3 > 1.2.3-rc.1 > 1.2.3-beat.1 > 1.2.3-alpha.1

homepage(主页)

可以写项目官网地址也可以写 github 地址等

"homepage": "https://github.com/owner/project#readme"

repository(仓库地址)

项目仓库地址

"repository": {
    "type": "git",
    "url": "https://github.com/xxx/xxx.git"
  }

license(开源许可证)

软件包指定的许可证,可以让使用者知道如何使用你的包,比如常用的有MIT,Apache,ISC等

{
  "license" : "MIT"
}

author(作者)

"author": "Cai xukun",

如果有多个维护者可以这样写

  "authors": [
    {
      "name": "Cai xukun",
      "email": "xukun@example.com",
      "url": "https://github.com/xukun"
    },
    {
      "name": "Kunkun",
      "email": "Kunkun@example.com",
      "url": "https://github.com/Kunkun"
    }
  ],

bugs

项目问题反馈地址,通常是 github 的 issue

"bugs": "https://github.com/xxx/issues"

keywords(关键词)

项目的关键词,可用于 npm 上检索

"keywords": [
  "ikun",
  "chicken",
  "sing",
  "jump",
  "rap",
  "basketball"
 ],

脚本

scripts

我们都知道在我们想要启动一个项目的时候都会执行npm run xxx,而这里就是在scripts字段中配置的

 "scripts": {
    "dev": "vite",
    "build": "vue-tsc && vite build",
    "preview": "vite preview"
  }

配置

config

config 可以定义项目的配置,比如环境变量

 "config": {
    "baseUrl": "https://xxxx"
  }

但通常我们都会把配置写到.env文件中

依赖

dependencies(生产依赖)

生产环境依赖,用于打包后项目的实际应用的包

  "dependencies": {
    "vue": "3.3.4"
  },

devDependencies(开发依赖)

开发环境的依赖,比如跟构建工具相关依赖vite,webpack等帮助我们开发时使用的包

 "devDependencies": {
    "@vitejs/plugin-vue": "^4.2.0",
    "vite": "^4.3.5",
    "typescript": "^4.9.3",
    "vue-tsc": "~1.0.24"
  }

同时我们会看到安装包的版本上会有^,~等符号,它们代表的意思分别是

~符号,它会匹配最新的 Patch 版本依赖包,比如~1.2.3会匹配所有不低于1.2.3版本的1.2.x版本并找到最新的一个进行安装
^会匹配最新的次版本号 Minor 依赖包,1.2.3,比如^1.2.3会匹配所有不低于1.2.3版本的1.x.x版本并找到最新的一个进行安装
*会匹配所有版本并找到最新的一个,也就是说它会安装最新的包

除了这两个常用的依赖字段还有peerDependencies(对等依赖),bundledDependencies(捆绑依赖),optionalDependencies(声明可选依赖项)等一些不常用的字段

系统相关

engines

engines 可以限制用户使用项目时 npm 和 node 的版本,比如

{
  "engines": {
    "node": ">=8.0.0 7.0.0"
  }
}

os

很明显它是规定项目可以运行的操作系统

{
  "os": [
    "windows",
    "linux"
  ]
}

cpu

指定 cpu 架构


{
  "cpu": [
    "x64",
    "ia32"
  ]
}

发布配置

private(私有)

将 private 设置为 true 可以防止将其发布到 npm 上(比如你的项目并不是一个 npm 包)

"private":true

publishConfig(发布配置)

publishConfig 是一个配置合集,可以配置一些 npm 发布时的一些参数,比如是否发布到公共仓库access,tag等

"publishConfig": {
  "tag": "1.0.0",
  "registry": "https://easyest.npmjs.org/",
  "access": "public"
}

preferGlobal

假如你发布的包需要让全局安装时候将其设置为 true 时候,如果用户局部安装了则会给用户一个提示

文件相关

files(文件)

files 字段包含了你需要推送到 npm 上的文件(如果你开发的是一个 npm 包的话)

  "files": [
    "index.js",
    "dist"
  ],

main(入口)

main 代表包的入口文件,不设置则默认根目录下的index.js

"main":"index.js"

browser(浏览器入口)

浏览器环境下的入口文件

bin(可执行命令)

指定将模块安装为全局可执行命令时的可执行文件的入口点,通常在开发脚手架的时候会用到,比如你的包配置了

"name":"mypkg",
"bin":"./bin/my-command.js"

当全局安装此包时npm i mypkg -g,就会创建一个mypkg的全局命令,输入mypkg命令就会执行./bin/my-command.js文件。当然如果你不像以包名为全局命令你可以这样写

 "name": "mypkg",
 "bin": {
    "my-command": "./bin/my-command.js"
  }

此时的全局命令则是my-command

workspaces(工作区)

了解过 Monorepo 对这个字段应该并不陌生,用来 workspaces 则表示你的一个代码库中有多个 npm 包,而这些包可以在本地互相引用,并且共享依赖项,比如你的配置

"workspaces": [
    "packages/*"
  ]

那么所有在 packages 目录下的子目录都属于工作区。然后，你可以在工作区的子包中，通过包名来引用其他子包。如在一个子包的 package.json 中

{
  "name": "my-package-1",
  "version": "1.0.0",
  "dependencies": {
    "my-package-2": "1.0.0"
  }
}

这将会让 my-package-1 依赖于 my-package-2，并且 npm 会自动处理它们之间的依赖关系。在my-package-1可以直接运行npm i my-package-2即可关联到本地的my-package-2进行使用。不过目前流行的Monorepo管理方式是使用pnpm,感兴趣的可以看这篇文章Monorepo 项目搭建

以上配置都是 node 的官方配置字段,除了这些还有一些是第三方打包工具比如 vite,rollup,webpack 等支持的字段

第三方配置

type

它可以指定项目模块的使用方式,如module,umd,commonjs,如我们项目使用的是 ES module 的导入方式

"type":"module"

指定完类型后如果有的地方你还是想用commonjs可以将文件名更改成xx.cjs形式即可

typings

用于指定 TypeScript 项目中的类型定义文件（.d.ts 文件）的位置,现在一般不推荐使用,从 TypeScript 2.0 版本开始，推荐使用 @types 作为类型定义文件的管理方式，而不再使用 typings 字段。你可以通过 npm 包管理器安装 @types 定义文件，例如：

npm install --save-dev @types/jquery

module

指定 ES 模块的入口字段,如果环境支持 ESModule 则会选择这个字段的入口文件而不是 main 字段对应的入口

"module": "dist/index.js"

exports

它也是指定项目的入口文件字段,如果你的打包工具支持此字段如 webpack,rollup,vite 等,那么它的优先级将会是最高的,它的用法有以下几种,其中"."表示默认导出,可以配置根据运行时的环境来选择不同的入口点

"exports": {
    ".": {
      "import": "./src/index.js",
      "require": "./lib/index.js"
    }
  }

它也可以让你在项目中使用相对路径来引用模块，而不是使用完整的文件路径或模块名。比如

{
  "exports": {
    "./lib/main": "./src/main.js"
  }
}

当你使用路径./lib/main时候实际加载的则是./src/main.js

browserslist

支持的浏览器列表

  "browserslist": [
    "last 2 versions",
    "> 1%",
    "Firefox > 20",
    "not IE 11"
  ]

sideEffects(副作用)

用来告知打包工具，模块中哪些文件是无"副作用"的，从而可以安全地进行 tree shaking 或者死代码消除。比如新建一个文件aaa.js代码如下

import "./index.css";
export const a = 1;
export const b = 2;

然后你需要导入aaa.js

import { a } from "./aaa.js";
console.log(a);

假如你没有配置sideEffects,那么打包工具就不知道下面的代码对你所导入的 css 文件对有没有影响,在你执行打包的时候 aaa.js 就不会tree shaking,即b也会被打包进去。然后你进行如下配置

"sideEffects": ["*.css"]

在这里，所有匹配到的文件都被视为无副作用的。所以此时打包工具知道了index.css是无副作用的,此时便进行了tree shaking,所以说正确配置 sideEffects 字段有助于提高打包效率，缩小最终打包文件的大小。但是，你需要确保正确标记了所有有副作用的文件，否则在摇树过程中可能会移除重要的代码，导致运行时错误。

eslintConfig

eslint 的配置字段,如

"eslintConfig":{
    "env": {
    "browser": true,
    "node": true,
    "es2021": true
  },
  "parser": "vue-eslint-parser",
  "extends": [
    "eslint:recommended",
    "plugin:vue/vue3-recommended",
    "plugin:@typescript-eslint/recommended",
    "plugin:prettier/recommended",
    "eslint-config-prettier"
  ]
}

不过一般来说 eslint 的配置一般会放在.eslintrc文件中

babel

babel 的配置字段

"babel": {
	"presets": ["@babel/preset-env"],
	"plugins": [...]
}

同样的 babel 的配置一般会放在.babelrc中

unpkg

unpkg 字段通常不包含在 package.json 中,它是一个用于在 unpkg.com 网站上托管和访问你的 npm 包的特殊配置。它允许开发者通过 URL 访问特定版本的 npm 包，而无需在自己的项目中安装这些包。比如

当你发布一个包的时候,默认情况下都可以通过unpkg.com进行访问

lint-staged

在进行 Git 提交的时候,对指定文件进行 lint 或其他预检查的工具。它通常与 husky（Git 钩子管理工具）一起使用

{
  "lint-staged": {
    "*.js": "eslint",
    "*.css": "stylelint",
    "*.md": "markdownlint"
  }
}

gitHooks

它是 husky 提供的配置选项,用于定义和配置 Git 钩子（Git Hooks）的行为,比如配置代码 commit 前与 push 前要做的事情

  "gitHooks": {
    "pre-commit": "lint-staged",
    "pre-push": "npm run xxx"
  }

具体 husky 相关配置可以查看这篇文章介绍引入 Husky 规范 git 提交

以上就是package.json字段的全部介绍了,如果对你有帮助的话,欢迎点赞收藏加关注!

参考文章:juejin.cn/post/702353…

关于 package.json 你了解多少?