- 概述
- name字段
- version字段
- description字段
- keywords字段
- homepage字段
- bugs字段
- license字段
- author字段、contributors字段
- files字段
- main字段
- bin字段
- man字段
- directories字段
- repository字段
- scripts字段
- config字段
- dependencies字段,devDependencies字段
- peerDependencies字段
- bundledDependencies字段
- optionalDependencies字段
- engines字段
- os字段
- cpu字段
- private字段
- publishConfig字段
- preferGlobal字段
- browser字段
- dependencies、devDependencies、peerDependencies 的区别
- 参考来源
概述
前端工程化项目,都会看到每个项目的根目录下一般都有一个package.json文件,这个文件定义了当前项目所需要的各种模块,以及项目的配置信息(比如名称、版本、许可证等)。
当运行npm install命令的时候,会根据package.json文件中的配置自动下载所需的模块,也就是配置项目所需的运行和开发环境。
package.json文件是一个JSON对象,这从他的后缀名.json就可以看出来,该对象的每一个成员就是当前项目的一项设置。
一份比较完整的配置项如下:
name字段
package.json文件中最重要的就是name和version字段,这两项是必填的。名称和版本一起构成一个标识符,该标识符被认为是完全唯一的。对包的更改应该与对版本的更改一起进行。
name必须小于等于214个字符,不能以 . 或 _ 开头,不能有大写字母,因为名称最终成为URL的一部分因此不能包含任何非URL安全字符。 npm官方建议我们不要使用与核心节点模块相同的名称。不要在名称中加js或node。如果需要可以使用engines来指定运行环境。
该名称会作为参数传递给require,因此它应该是简短的,但也需要具有合理的描述性。
version字段
version 一般的格式是x.x.x,并且需要遵循该规则。
package.json 文件中最重要的就是 name 和 version 字段,这两项是必填的。名称和版本一起构成一个标识符,该标识符被认为是完全唯一的。每次发布时version不能与已存在的一致。
description字段
description 是一个字符串,用于编写描述信息。有助于人们在 npm 库中搜索的时候发现你的模块。
keywords字段
keywords 是一个字符串组成的数组,有助于人们在 npm 库中搜索的时候发现你的模块。
homepage字段
homepage 项目的主页地址。
bugs字段
bugs 用于项目问题的反馈issue地址或者一个邮箱。
"bugs": {
"url": "https://github.com/xxx/project/issues",
"email": "project@hostname.com"
}
license字段
license 是当前项目的协议,让用户知道他们有何权限来使用你的模块,以及使用该模块有哪些限制。
author字段、contributors字段
author 是具体一个人, contributors 表示一群人,他们都表示当前项目的共享者。同时每个人都是一个对象。具有 name 字段和可选的 url 及 email 字段。
"author": {
"name": "xxx",
"email": "xxx",
"url": "xxx"
}
也可以写成一个字符串
"author": "xxx xxx@xx.com (https://xxx/com)"
files字段
files 属性的值是一个数组,内容是模块下文件名或者文件夹名,如果是文件夹名,则文件夹下所有的文件也会被包含进来(除非文件被另一些配置排除了)
可以在模块根目录下创建一个 .npmignore 文件,写在这个文件里的文件几遍被写在files属性里边也会被排除在外,这个文件的写法与 .gitignore 类似。
main字段
main字段指定了加载的入口文件,require 导入的时候就会加载这个文件。这个字段的默认值是模块根目录下面的 index.js。
bin字段
bin 项用来指定每个内部命令对应的可执行文件的位置。如果你编写的是一个node工具的时候一定就会用到 bin 字段。
当我们编写一个cli 工具的时候,需要指定工具的运行命令,比如常用的 webpack 模块,其运行命令就是 webpack。
"bin": {
"webpack": "bin/index.js"
}
当我们执行 webpack 命令的时候就会执行 bin/index.js 文件中的代码。
在模块以依赖的方式被安装,如果存在 bin 选项。在 node_module/.bin/生成对应的文件, npm 会寻找这个文件,在node_module/.bin/ 目录下建立符号链接。由于 node_module/.bin/ 目录会在运行时加入系统的PATH 变量,因此在运行npm 时,就可以不带路径,直接通过命令来滴调用这些脚本。
所以 node_module/.bin/ 目录下的命令,都可以用npm run 【命令】的格式运行。在命令行下,键入 npm run,然后按tab 键,就会显示所有可以使用的命令。
man字段
man用来指定当前模块的man文档的位置。
"man": ["./doc/calc.1"]
directories字段
directories 指定一些方法来描述模块的结构,用来告诉用户每个目录在什么位置。
repository字段
指定一个代码存放的地址,对想要为你的项目贡献代码的人有帮助
"repository": {
"type": "git",
"url": "https://github.com/npm/npm.git"
}
scripts字段
scripts指定了运行脚本命令的 npm 命令行缩写,比如start 指定了 运行 npm run start时,所要执行的命令。
"scripts": {
"start": "node ./start.js"
}
使用scripts 字段可以快速的执行 shell命令,可以理解为 alias。
scripts 可以直接使用 node_modules中安装的模块,这区别于直接运行需要使用 npx 命令。
"scripts": {
"build": "webpack"
}
// npm run build
// npx webpack
config字段
config 字段用于添加命令行的环境变量。
{
"name": "xxx",
"config": {
"port": "8080"
},
"scripts": {
"start": "node server.js"
}
}
然后,在server.js 脚本就可以引用config 字段的值。
console.log(process.env.npm_package_config_port); // 8080
用户可以通过 npm config set 来修改这个值。
npm config set xxx:port 8000
dependencies字段,devDependencies字段
dependencies 字段指定了项目运行所依赖的模块, devDependencies 指定项目开发所需要的模块。
它们的值都是一个对象。该对象的各个成员,分别有模块名和对应的版本要求组成,标识依赖的模块及其版本范围。
当安装依赖的时候使用 —save 参数标识将该模块写入dependencies属性, —save-dev 表示将该模块写入 devDependencies 属性。
"devDependencies": {
"webpack": "^5.38.1"
}
对象的每一项通过一个键值对表示,前面是模块名称,后面是对应模块的版本号,版本号遵循”大版本.次要版本.小版本“的格式规定。
版本说明 固定版本 比如5.38.1,安装时只安装指定版本。 波浪号: 比如~5.38.1, 表示安装5.38.x的最新版本(不低于5.38.1),但是不安装5.39.x,也就是说安装时不改变大版本号和次要版本号。 插入号: 比如^5.38.1, ,表示安装5.x.x的最新版本(不低于5.38.1),但是不安装6.x.x,也就是说安装时不改变大版本号。需要注意的是,如果大版本号为0,则插入号的行为与波浪号相同,这是因为此时处于开发阶段,即使是次要版本号变动,也可能带来程序的不兼容。 latest: 安装最新版本。
peerDependencies字段
当我们开发一个模块的时候,如果当前模块与所依赖的模块同时依赖一个第三方模块,并且依赖的是两个不兼容的版本时就会出现问题。
例如,项目依赖A模块和B模块的1.0.0版本,而A模块本身又依赖B模块的2.0.0版本。
大多数情况下,这不构成问题,B模块的两个版本可以并存,同时运行。但是,有一种情况,会出现问题,就是这种依赖关系将暴露给用户。
最典型的场景就是插件,比如A模块是B模块的插件,用户安装的B模块是1.0版本,但是A插件只能和2.0版本的B模块一起使用。这时,用户要是将1.0.0版本的B的实例传给A,就会出现问题。因此,需要一种机制,在模板安装的时候提醒用户,如果A和B一起安装,那么N必须是2.0.0模块。
peerDependencies字段,就是用来供插件指定其所需要的主工具的版本。可以通过 peerDependencies 字段来限制,使用 myless模块必须依赖less模块的3.9.x版本。
{
"name": "myless",
"peerDependencies": {
"less": "3.9.x"
}
}
注意,从npm 3.0版本开始, peerDependencies 不再默认安装了,就是初始化时不会默认带出。
bundledDependencies字段
bundledDependencies 指定发布的时候会被一起打包的模块。
optionalDependencies字段
如果一个依赖模块可以被使用,同时你也希望在该模块找不到或无法获取时 npm继续运行,可以把这个模块依赖放到 optionalDependencies 配置中。这个配置的写法和 dependencies 的写法一样,不同的是这里边写的模块安装失败不会导致 npm install失败。
engines字段
engines 字段指明了该模块运行的平台,比如 node或者npm 的某个版本或者浏览器。
{
"engines": {
"nodes": ">=0.10.3 <0.12",
"npm": "~1.0.20"
}
}
os字段
"os": ["darwin", "linux", "win32"]
cpu字段
限制模块只能在某种架构的 cpu下运行
"cpu": ["x64", "ia32"]
private字段
如果这个属性被设置为 true, npm将拒绝发布它,这是为了防止一个私有模块被无意间发布出去。
"private": true
publishConfig字段
这个配置是会在模块发布时生效,用于设置发布用到的一些值的集合。如果不想模块被默认标记为最新的,或者默认发布到公共仓库,可以在这里配置tag或仓库地址。
通常publishconfig 会配合 private 来使用,如果只想让模块被发布到一个特定的 npm 仓库,如一个内部的仓库。
"private": true,
"publishConfig": {
"tag": "1.0.0",
"registry": "https://registry.npmjs.org/",
"access": "public"
}
preferGlobal字段
preferGlobal 的值是布尔值,表示当用户不将该模块安装为全局模块时(即不用-global参数),要不要显示警告,表示该模块的本意就是安装为全局模块。
"preferGlobal": false
browser字段
browser 指定该模板供浏览器使用的版本。 Browserify 这样的浏览器打包工具,通过它就知道该打包哪个文件。
"browser": {
"tipso": "./node_modules/tipso/src/tipso.js"
}
dependencies、devDependencies、peerDependencies 的区别
- 应用运行时必须的,写在 “dependencies”: {} 里。比如:lodash,注意不要把测试工具编译器放在 “dependencies”: {} 里。他们都是开发时依赖的放在 “devDependencies”: {} 即可。
- 开发时需要,但运行时用不上的,写在 “devDependencies”: {} 里。比如:typescript,因为 ts 最终都会编译成 js 执行,运行时就没 ts 什么事了。还比如测试工具也同理。
- 运行时需要,但是我自己不附带,我知道你的环境里肯定得有这个包,这种情况写在 “peerDependencies”: {} 里。举个例子:比如你要写一个 react 应用,要用到 A 这个库,A 也依赖 react,但是安装 A 的时候,A 不附带 react,因为 A 知道你的环境里一定有 react,所以 A 只需要告诉你它最低依赖的 react 是什么版本就可以了。而不需要自带 react。
参考来源
- [1] npm package.json
- [2] javaScript标准参考教程