package.json 是一个用于描述和配置项目的重要文件,其中包含了许多字段和选项,可以影响项目的构建、依赖管理、脚本执行等方面。了解这些字段可以帮助开发者更好地理解和控制项目的行为。
package.json对于大部分前端开发者来说,知道dependencies与devDependencies就够了。但对于库开发者或有更高级需求的开发者来说,了解 package.json 的其他字段是非常有必要的。
本文介绍的字段分为官方字段与非官方字段。非官方字段是被主流打包工具(webpack,Rollup)所支持, 旨在提供更高级的配置和功能,以满足特定的构建需求,可能不具备通用性。
目前版本:v7.24.2
一、必须属性
1. name
定义项目的名称,不能以"."和"_"开头,不能包含大写字母
定义项目的版本号,格式为:大版本号.次版本号.修订号
二、描述信息
1. description项目描述2. keywords项目关键词3. author项目作者
"author": "name (http://barnyrubble.tumblr.com/)"
项目贡献者
"contributors": [ "name (http://barnyrubble.tumblr.com/)" ]
项目提交问题的地址 //提交问题的地址和反馈的邮箱,url通常是Github中的issues页面"bugs": { "url" : "https://github.com/facebook/react/issues", "email" : "xxxxx@xx.com"}
"funding": { "type": "patreon", "url": "https://www.patreon.com/my-module" }
三、依赖配置
"peerDependencies": { "react": ">17.0.1" }
将对等依赖标记为可选,如果用户没有安装对等依赖,npm不会发出警告
"peerDependenciesMeta": { "react": { "optional": true //标记为可选 } }
"engines": { "node": ">=8.10.3 =6.9.0" }
engines只是起一个说明的作用,即使用户安装的版本不符合要求,也不影响依赖包的安装。
单个代码库中统一管理多个包(monorepo),在workspaces声明目录下的package会软链到根目录的node_modules中。
npm init -y
"private":"true", "workspaces": [ "packages/*" ],
表示所有子包都在packages文件夹下
npm init -w packages/p1 -y
在node_modules/.package-lock.json中可以看到 "link": true 链接符号信息
module.exports = "p1包";
npm init -w packages/p2 -y
npm i p1 -w p2
安装,卸载等命令都是一样的,只是多了"--workspace="参数(简写-w),用来指定在哪个包中执行命令
const p1 = require("p1");console.log("使用", p1);module.exports = "p2包";
workspaces功能与lerna类似,如果只需简单地管理多个包,workspaces足够了。lerna具有版本管理,发包提示,简化多包项目发布流程等更多功能。
四、脚本配置
脚本入口
用于定义项目的配置项,例如设置环境变量
"config": { "baseUrl": "https://example.com" }
"scripts": { "start": "node index.js", },
//使用process.env.npm_package_config_XXX取值console.log(process.env.npm_package_config_baseUrl)
运行 npm run start,终端打印出 example.com五、文件&目录1. module(非官方字段)指定 ES 模块入口文件示例:当其他开发者在他们的项目中导入你的包时,会加载并执行包中的dist/index.esm.js
"main": "dist/index.esm.js"
"exports": { ".": { "import": "./dist/index.esm.js", "require": "./dist/index.cjs.js", "browser": "./dist/index.umd.js", "types": "./dist/index.d.ts" } }
导出其他文件,例如除了导出默认路径,导出源文件
"exports":{ ... "./main" : "./src/main.js"},
其他项目中使用
import main from 'packageName'; // . 方式定义的import main from 'packageName/main'; // ./main 方式定义的
"type":"module"
"files": [ "index.js", "dist" ],
可以在项目根目录新建一个.npmignore文件,说明不需要提交到npm服务器的文件,类似.gitignore。写在这个文件中的文件即便被写在files属性里也会被排除在外
定义在全局安装时可执行的命令(使用情景较少)
Linux 中的帮助指令(使用情景较少)
定义项目目录结构的字段(使用情景较少)
六、发布配置
防止私有包发布到npm服务器,要发布到npm上设为false
当设置 "preferGlobal" 字段为 true 时,它表示你的包更适合以全局方式安装,而不是作为项目的依赖项进行本地安装。
这个字段的设置是为了向用户传达关于你的包的最佳使用方式的建议。它并不会直接影响包的安装方式或包管理器的行为。
在发布包时指定特定的配置
示例:指定包发布的注册表 URL,指定所有用户都可以访问(私有的会收费)
"publishConfig": { "registry": "https://registry.npmjs.org/", "access": "public" }
"os": ["darwin", "linux"]
示例:禁用win32
"os" ["!win32"] //禁用的操作系统
该配置和OS配置类似,用CPU可以更准确地限制用户的安装环境
指定软件的开源协议:
ISC:在所有副本中保留版权声明和许可证声明,使用者就可以拿你的代码做任何想做的事情,你也无需承担任何责任
MIT:在所有副本或主要部分中保留版权声明和许可证声明,使用者就可以拿你的代码做任何想做的事情,你也无需承担任何责任
开源协议查询地址:opensource.org/licenses/
七、第三方配置(非官方字段)
eslint的配置,更推荐新建 .eslintrc 进行配置
babel的配置,更推荐新建 .babelrc 进行配置
unpkg 是一个基于 CDN 的前端包托管服务,用于在浏览器中直接引用和加载 npm 上发布的包。
无需下载,直接通过 标签引用
告知支持哪些浏览器及版本,Autoprefixer常用到它
"browserslist": [ "defaults", "not ie 1%", "iOS 7", "last 3 iOS versions" ]
指示包是否具有副作用,协助Webpack,Rollup等进行tree shaking
多数情况下可以直接设置为false,这样打包工具就会自动删除未被import的代码
但是有些情况例外
2. 告诉构建工具不要将样式文件排除在无用代码消除的优化范围之外
"sideEffects": ["./path/to/module.js", "*.css"]