前端 package.json 的每一项作用
在 Node.js 项目中,package.json 是一个非常重要的配置文件,它包含了项目的元数据和配置信息。下面是所涉及到的字段含义和它的使用场景,避免一些配置性的错误,提高项目的维护性。
文章目录
name:
- 作用: 指定包的名称,项目是需要发版为 npm 包的,name 则必填。
- 注意事项: 包名必须是唯一的,且符合 npm 的包命名规范。
- 私源 npm 包命名格式:
name:@[scope]/[name]
{
"name": "custom-npm-xxx"
//...
}
version:
- 作用: 指定包的当前版本号。
- 版本号格式:
X.Y.Z[-string]
,参考以下规范 ↓- X:主版本号
- Y:次版本号
- Z:修正版本号
- string: 先行版本号或版本编译信息
{
"version": "2.3.2"
//...
}
2.3.2-alpha的含义为:
主版本号2,有2次不可向下兼容的更新迭代。
次版本号3,有3次小的功能迭代。2.*.* <=2.3.2的依赖声明,都可以安装此新包。
修正版本号2,有2次bug修改或其他非重大功能的修改。2.*.* <=2.3.2的依赖声明,都可以安装此新包。
先行版本号alpha,表示处理试验阶段。
package.json 识别依赖版本
{
"vue": "~2.5.22",
"vue-class-component": "^6.0.0",
"vue-router": "3.0.1",
"express": "latest",
"mongoose": "*"
}
-
符号^
:锁定主版本,可更新次版本号、修正版本号和先行版本号- 例如"vue-class-component": “^6.0.0”,安装依赖时,可以安装符合 6.. 的任意版本,只要主版本号是 6 即可。
-
符号~
:锁定主版本号和次版本号,可更新修正版本号和先行版本号- 例如"vue": “~2.5.22”,安装依赖时,可以安装符合 2.5.*的任意版本。
-
空符号
:锁定所有版本号- 例如"vue-router": “3.0.1”,只能安装版本为 3.0.1 的依赖包。
-
符号*
:定义某个版本号范围- 例如 vue-router": “3.0.*”,可以安装 3.0 固定的任意版本,比如 3.0.1、3.0.2。
-
latest
:安装最新的稳定版本。 -
安装最新发布的版本,不一定是稳定版本。
-
Git URL
:使用 Git 上发布的包。
dependencies:
- 作用: 指定包运行时的依赖项,生产环境中使用到的依赖,安装在该配置项下。
- 注意事项: 使用对象格式,键为依赖包名称,值为版本号范围或者 URL。
{
"name": "custom-npm-xxx",
"dependencies": {
"express": "^4.17.1",
"lodash": "^4.17.21"
}
//...
}
devDependencies:
- 作用: 开发环境依赖项,仅在开发过程中需要的包,生产环境下是不会安装 devDependencies 字段下的依赖的。
- 注意事项: 通常包含测试框架、打包工具等。
{
"name": "custom-npm-xxx",
"devDependencies": {
"eslint": "^7.32.0",
"mocha": "^9.1.3"
}
//...
}
peerDependencies:
- 作用: 当开发一些插件和工具包时,对使用方的运行环境的依赖包版本有要求,可以使用 peerDependencies 字段进行声明。
- 注意事项: peerDependencies 在 npm 包的依赖关系处理中,很重要。
//假如UI组件库antd的package.json中, peerDependencies要求使用React 16,那么我们项目的react版本必须是大于或者等于此版本。
{
"name": "antd",
"peerDependencies": {
"react": ">=16.8.0"
}
//...
}
scripts:
- 作用: 定义可通过 npm 运行的脚本命令,令在开发、测试、构建和部署等阶段都非常有用。
{
"name": "custom-npm-xxx",
"scripts": {
"dev": "vite --mode dev",
"build": "run-p type-check \"build-only {@}\" --",
"preview": "vite preview",
"test:unit": "vitest",
"build:test": "vite build --mode dev",
"build:prod": "vite build --mode prod",
"type-check": "vue-tsc --build --force",
"lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
"format": "prettier --write src/"
}
//...
}
description:
- 作用: 对包的简短描述。
- 注意事项: 提供清晰而简洁的说明,帮助他人了解包的功能。
private:
- 作用: 布尔值,指定该包是否是私有的(不应该发布到 npm),这是防止意外发布个人仓库的一种保护方式。
- 注意事项: 默认为 false,仅在不希望该包被误发布时设置为 true。
publishConfig:
- 作用: 定义发布 npm 时,设置相关信息。
// registry 发布的npm私源地址
// access 发布有作用域的包,必须要设置access。
// tag 指定当前版本对应的标签
{
"name": "custom-npm-xxx",
"publishConfig": {
"registry": "http://npm.xxx/repository/",
"access": "public",
"tag": "xxx"
}
//...
}
keywords:
- 作用: 关键字数组,描述包的特性,便于他人搜索和分类。
- 注意事项: 使用相关的关键词,使得包更容易被发现。
main:
- 作用: 指定包的入口文件。
- 注意事项: 默认情况下是 index.js,但可以根据需要指定其他入口文件。
module:
- 作用: 指定 ES 模块的入口文件。
- 注意事项: 当 type 设置为 “module” 时,指定项目的 ES 模块入口。
types:
- 作用:项目如果是用 TypeScript 写的,则需要 types 字段,对外暴露相关的类型定义。
type:
- 作用: 指定模块的类型,可以是 “module”(ES 模块)或 “commonjs”(CommonJS 模块)。
- 注意事项: 当前 Node.js 支持的模块系统配置。
homepage:
- 作用: 指定包的主页 URL。
- 注意事项: 可以是 GitHub 页面、个人网站等,提供更多关于包的信息和文档。
repository:
- 作用: 指定代码仓库的位置。
- 注意事项: 使用对象格式,包括 type(版本控制系统,如 “git”)和 url(仓库 URL)字段。
{
"name": "custom-npm-xxx",
"repository": {
"type": "git",
"url": "https://github.com/username/my-project.git"
}
//...
}
engines:
- 作用: 指定项目运行所需的 Node.js 版本范围。
// 下面代码,告知node版本需要在0.10.3与15之间,才可以运行当前项目。
// 在不符合条件的环境中运行项目时,控制台会有报错输出。
{
"name": "custom-npm-xxx",
"engines": {
"node": ">=0.10.3 <15"
}
//...
}
bugs:
- 作用: 开源项目用于接收 bug 反馈。
{
"name": "custom-npm-xxx",
"bugs": {
"url": "https://xxx",
"email": "project@xxx.com"
}
//...
}
license:
- 作用: 指定包的许可证。
- 注意事项: 指定许可证的缩写或者 URL,表明其他人在使用你的包时需要遵循的规定。
author:
- 作用: 指定包的作者。
- 注意事项: 可以是个人名字或者组织名称。
contributors:
- 作用: 列出对包有贡献的人员列表。
- 注意事项: 使用数组格式,每个条目可以包含 name(姓名)和 email(邮箱)等信息。
files:
- 作用: 指定包发布到 npm 上时包含的文件和目录。
- 注意事项: 使用数组格式,列出相对于 package.json 的路径。
workspaces:
- 作用: 用于配置使用 Yarn 或者 npm 工作区(workspaces)特性的 monorepo(单仓库多包)项目。这种项目结构允许你在一个仓库中管理多个相关的包(如模块、库、应用等),而不需要每个包都拥有自己的独立仓库。
- 使用工作区特性可以简化依赖管理和版本控制,确保所有包使用相同的依赖版本,方便进行统一的构建、测试和发布。
{
"name": "custom-npm-xxx",
"version": "1.0.0",
"private": true,
"workspaces": ["packages/*"],
"dependencies": {
"lodash": "^4.17.21"
},
"devDependencies": {
"eslint": "^7.32.0",
"mocha": "^9.1.3"
}
//...
}
cpu:
- 作用: CPU 的要求声明。
{
"name": "custom-npm-xxx",
"cpu": ["x64", "ia32"]
//...
}
os:
- 作用: 操作系统的要求声明。
{
"name": "custom-npm-xxx",
"os": ["darwin", "linux"]
//...
}