前端 package.json 的每一项作用

前端 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"]//...
}

npm docs参考