package.json配置项详解

javascript/jquery

浏览数:7

2020-5-23

AD:资源代下载服务

package.json文件就是一个JSON对象,该对象的每一个成员就是当前项目的一项设置。npm install命令根据这个配置文件,自动下载所需的模块,也就是配置项目所需的运行和开发环境。

配置字段

name

项目名称

version

项目版本号

description

项目描述,便于用户在npm上搜索到我们的项目。

keywords

是一个字符串数组,便于用户在npm上搜索到我们的项目。

homepage

项目url主页,例如:
"homepage": "https://github.com/owner/project#readme"

bugs

项目问题反馈的Url或报告问题的email地址。例如:
{ "url" : "https://github.com/owner/project/issues" , "email" : "project@hostname.com" }
若只设置url,则bugs可用字符串来代替对象。
"bugs":"https://github.com/owner/project/issues"

license

项目许可证,让使用者知道如何使用此项目。

author,contributors

author是一个person,contributors是person的数组。一个person是一个对象,包含name、url和email。例如:
{ "name" : "Barney Rubble" , "email" : "b@rubble.com" , "url" : "http://barnyrubble.tumblr.com/"}

files

files是一个文件数组,描述了将软件包作为依赖项安装时要包括的条目。如果在数组里面声明了一个文件夹,那也会包含文件夹中的文件。某些特殊文件和目录也被包括或排除在外,无论它们是否存在于文件数组中。

以下文件无论是否设置,总是包含:
*   `package.json`
*   `README`
*   `CHANGES`/`CHANGELOG`/`HISTORY`
*   `LICENSE`/`LICENCE`
*   `NOTICE`
*   The file in the “main” field

以下文件总是被忽略:
*   `.git`
*   `CVS`
*   `.svn`
*   `.hg`
*   `.lock-wscript`
*   `.wafpickle-N`
*   `.*.swp`
*   `.DS_Store`
*   `._*`
*   `npm-debug.log`
*   `.npmrc`
*   `node_modules`
*   `config.gypi`
*   `*.orig`
*   `package-lock.json`(use shrinkwrap instead)

main

主文件。比如默认是index.js,项目名称叫foo。那么require(“foo”)将返回index.js返回的内容。路径相对软件包根目录。

browser

如果要在客户端使用模块,则应使用browser字段来代替main字段。

bin

bin用来指定各个内部命令对应的可执行文件的位置。例如:myapp里面包含

"bin": {
  "someTool": "./bin/someTool.js"
}

上面代码指定,someTool 命令对应的可执行文件为 bin 子目录下的 someTool.js。当本地安装myapp时,Npm会寻找这个文件,在./node_modules/.bin/目录下建立符号链接。在上面的例子中,someTool.js会建立符号链接./node_modules/.bin/someTool。由于./node_modules/.bin/目录会在运行时加入系统的PATH变量,因此在运行npm时,就可以不带路径,直接通过命令来调用这些脚本。

所有node_modules/.bin/目录下的命令,都可以用npm run [命令]的格式运行。bin中引用的文件需以#!/usr/bin/envnode开头

man

用来指定当前模块的man文档的位置。例如:

{ "name" : "foo", "version" : "1.2.3", "description" : "A packaged foo fooer for fooing foos", "main" : "foo.js", "man" : "./man/doc.1"}

该配置会在执行man foo时,使用./man/doc.1这个文件。

directories

CommonJS包规范详细介绍了几种使用directories对象来标识包结构的方法。如果您查看npm的package.json,就会看到它有doc、lib和man目录。

  • directories.lib:库文件夹的位置。
  • directories.bin:如果你在directories.bin中指定一个bin目录,在这个目录中的所有文件都会被当做在bin来使用。由于bin指令的工作方式,同时指定一个bin路径和设置directories.bin将是一个错误。如果你想指定独立的文件,使用bin,如果想执行某个文件夹里的所有文件,使用directories.bin。
  • directories.man:全是man文件的文件夹,系统通过遍历这个文件夹来生成一个man的数组
  • directories.doc:把markdown文件放这里,也许有一天可以很好的展会出来。
  • directories.example:把示例脚本放这里,将来可能会用到
  • directories.test:把测试放这里,将来可能会用到

repository

代码存放地方。例如:

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

如果包的package.json不在根目录中,可以通过directory来声明他所在的位置。例如:

"repository": {
    "type": "git",
    "url": "https://github.com/facebook/create-react-app.git",
    "directory": "packages/react-scripts"
  },

scripts

scripts指定了运行脚本命令的npm命令行缩写,比如start指定了运行npm run start时,所要执行的命令。
下面的设置指定了npm run preinstallnpm run postinstallnpm run startnpm run test时,所要执行的命令。

"scripts": {
    "preinstall": "echo here it comes!",
    "postinstall": "echo there it goes!",
    "start": "node index.js",
    "test": "tap test/*.js"
}

config

用于添加命令行的环境变量。

{
  "name" : "foo",
  "config" : { "port" : "8080" },
  "scripts" : { "start" : "node server.js" }
}

server.js中使用process.env.npm_package_config_port来获取port。

用户可以通过执行npm config set foo:port 80来覆盖该命令

dependenciesdevdependencies

dependencies指定了项目运行所依赖的模块。devDependencies指定项目开发所需要的模块。对应的版本可以加上各种限定,主要有以下几种:

  • 指定版本:比如1.2.2,遵循“大版本.次要版本.小版本”的格式规定,安装时只安装指定版本。
  • 波浪号(tilde)+指定版本:比如~1.2.2,表示安装1.2.x的最新版本(不低于1.2.2),但是不安装1.3.x,也就是说安装时不改变大版本号和次要版本号。
  • 插入号(caret)+指定版本:比如ˆ1.2.2,表示安装1.x.x的最新版本(不低于1.2.2),但是不安装2.x.x,也就是说安装时不改变大版本号。需要注意的是,如果大版本号为0,则插入号的行为与波浪号相同,这是因为此时处于开发阶段,即使是次要版本号变动,也可能带来程序的不兼容。
  • latest:安装最新版本。

--save参数表示将该模块写入dependencies属性,--save-dev表示将该模块写入devDependencies属性。

peerdependencies

有时,你的项目和所依赖的模块,都会同时依赖另一个模块,但是所依赖的版本不一样。比如,你的项目依赖A模块和B模块的1.0版,而A模块本身又依赖B模块的2.0版。

大多数情况下,这不构成问题,B模块的两个版本可以并存,同时运行。但是,有一种情况,会出现问题,就是这种依赖关系将暴露给用户。

最典型的场景就是插件,比如A模块是B模块的插件。用户安装的B模块是1.0版本,但是A插件只能和2.0版本的B模块一起使用。这时,用户要是将1.0版本的B的实例传给A,就会出现问题。因此,需要一种机制,在模板安装的时候提醒用户,如果A和B一起安装,那么B必须是2.0模块。

peerDependencies字段,就是用来供插件指定其所需要的主工具的版本。

{
  "name": "chai-as-promised",
  "peerDependencies": {
    "chai": "1.x"
  }
}

上面代码指定,安装chai-as-promised模块时,主程序chai必须一起安装,而且chai的版本必须是1.x。如果你的项目指定的依赖是chai的2.0版本,就会报错。

注意,从npm 3.0版开始,peerDependencies不再会默认安装了。

bundleddependencies

定义一个数组,会在发布时将定义的模块一起打包。用于需在本地保存npm包或者下载单个文件时可用。例如:

{
  "name": "awesome-web-framework",
  "version": "1.0.0",
  "bundledDependencies": [
    "renderized", "super-streams"
  ]
}

运行npm pack命令会得到awesome-web-framework-1.0.0.tgz。执行npm install awesome-web-framework-1.0.0.tgz将在新项目中安装renderizedsuper-streams这两个依赖项

optionaldependencies

若希望在包找不到或者安装失败时,npm继续运行,可将该包放在optionalDependencies对象中。需要你在代码中处理模块缺失的问题。optionalDependencies会覆盖dependencies中同名的,所以最好只放在一个地方。

engines

engines字段指明了该模块运行的平台,比如 Node 的某个版本或者浏览器。该字段也可以指定适用的npm版本。

{ "engines" : { "node" : ">=0.10.3 <0.12" } }

os

指定你的项目将运行在什么操作系统上。

cpu

指定你的项目将运行在什么cpu架构上。

private

如果设置为true, 那么npm会拒绝发布它。

publishconfig

一组配置值,发布时使用。

参考自:
npm-package.json
package.json文件

作者:lijinxieyang