If you work with JavaScript, or you’ve ever interacted with a JavaScript project, Node.js or a frontend project, you surely met the package.json
file.
如果您使用JavaScript,或者曾经与JavaScript项目,Node.js或前端项目进行过交互,那么您肯定会遇到package.json
文件。
What’s that for? What should you know about it, and what are some of the cool things you can do with it?
那个有什么用途? 您应该了解什么,可以使用它完成哪些有趣的事情?
The package.json
file is kind of a manifest for your project. It can do a lot of things, completely unrelated. It’s a central repository of configuration for tools, for example. It’s also where npm
and yarn
store the names and versions of the package it installed.
package.json
文件是您项目的清单。 它可以做很多事情,完全无关。 例如,它是工具配置的中央存储库。 它也是npm
和yarn
存储安装的软件包的名称和版本的地方。
文件结构 (The file structure)
Here’s an example package.json file:
这是一个示例package.json文件:
{
}
It’s empty! There are no fixed requirements of what should be in a package.json
file, for an application. The only requirement is that it respects the JSON format, otherwise it cannot be read by programs that try to access its properties programmatically.
它是空的! 对于应用程序,对于package.json
文件中的内容没有固定要求。 唯一的要求是,它必须遵守JSON格式,否则,尝试以编程方式访问其属性的程序将无法读取它。
If you’re building a Node.js package that you want to distribute over npm
things change radically, and you must have a set of properties that will help other people use it. We’ll see more about this later on.
如果要构建要在npm
上分发的Node.js程序包,则情况将发生根本变化,并且必须具有一组可帮助其他人使用它的属性。 稍后我们将详细介绍。
This is another package.json:
这是另一个package.json:
{
"name": "test-project"
}
It defines a name
property, which tells the name of the app, or package, that’s contained in the same folder where this file lives.
它定义了一个name
属性,用于告诉应用程序或程序包的名称,该属性包含在该文件所在的同一文件夹中。
Here’s a much more complex example, which I extracted this from a sample Vue.js application:
这是一个更复杂的示例,我从示例Vue.js应用程序中提取了此示例:
{
"name": "test-project",
"version": "1.0.0",
"description": "A Vue.js project",
"main": "src/main.js",
"private": true,
"scripts": {
"dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
"start": "npm run dev",
"unit": "jest --config test/unit/jest.conf.js --coverage",
"test": "npm run unit",
"lint": "eslint --ext .js,.vue src test/unit",
"build": "node build/build.js"
},
"dependencies": {
"vue": "^2.5.2"
},
"devDependencies": {
"autoprefixer": "^7.1.2",
"babel-core": "^6.22.1",
"babel-eslint": "^8.2.1",
"babel-helper-vue-jsx-merge-props": "^2.0.3",
"babel-jest": "^21.0.2",
"babel-loader": "^7.1.1",
"babel-plugin-dynamic-import-node": "^1.2.0",
"babel-plugin-syntax-jsx": "^6.18.0",
"babel-plugin-transform-es2015-modules-commonjs": "^6.26.0",
"babel-plugin-transform-runtime": "^6.22.0",
"babel-plugin-transform-vue-jsx": "^3.5.0",
"babel-preset-env": "^1.3.2",
"babel-preset-stage-2": "^6.22.0",
"chalk": "^2.0.1",
"copy-webpack-plugin": "^4.0.1",
"css-loader": "^0.28.0",
"eslint": "^4.15.0",
"eslint-config-airbnb-base": "^11.3.0",
"eslint-friendly-formatter": "^3.0.0",
"eslint-import-resolver-webpack": "^0.8.3",
"eslint-loader": "^1.7.1",
"eslint-plugin-import": "^2.7.0",
"eslint-plugin-vue": "^4.0.0",
"extract-text-webpack-plugin": "^3.0.0",
"file-loader": "^1.1.4",
"friendly-errors-webpack-plugin": "^1.6.1",
"html-webpack-plugin": "^2.30.1",
"jest": "^22.0.4",
"jest-serializer-vue": "^0.3.0",
"node-notifier": "^5.1.2",
"optimize-css-assets-webpack-plugin": "^3.2.0",
"ora": "^1.2.0",
"portfinder": "^1.0.13",
"postcss-import": "^11.0.0",
"postcss-loader": "^2.0.8",
"postcss-url": "^7.2.1",
"rimraf": "^2.6.0",
"semver": "^5.3.0",
"shelljs": "^0.7.6",
"uglifyjs-webpack-plugin": "^1.1.1",
"url-loader": "^0.5.8",
"vue-jest": "^1.0.2",
"vue-loader": "^13.3.0",
"vue-style-loader": "^3.0.1",
"vue-template-compiler": "^2.5.2",
"webpack": "^3.6.0",
"webpack-bundle-analyzer": "^2.9.0",
"webpack-dev-server": "^2.9.1",
"webpack-merge": "^4.1.0"
},
"engines": {
"node": ">= 6.0.0",
"npm": ">= 3.0.0"
},
"browserslist": [
"> 1%",
"last 2 versions",
"not ie <= 8"
]
}
there are lots of things going on here:
这里发生了很多事情:
name
sets the application/package namename
设置应用程序/程序包名称version
indicates the current versionversion
指示当前版本description
is a brief description of the app/packagedescription
是应用程序/软件包的简短描述main
set the entry point for the applicationmain
设置应用程序的入口点private
if set totrue
prevents the app/package to be accidentally published onnpm
如果设置为
true
则为private
,以防止应用程序/软件包在npm
上意外发布scripts
defines a set of node scripts you can runscripts
定义了一组可以运行的节点脚本dependencies
sets a list ofnpm
packages installed as dependenciesdependencies
设置作为依赖项安装的npm
软件包列表devDependencies
sets a list ofnpm
packages installed as development dependenciesdevDependencies
设置作为开发依赖项安装的npm
软件包列表engines
sets which versions of Node this package/app works onengines
设置此程序包/应用程序在哪个版本的Node上运行browserslist
is used to tell which browsers (and their versions) you want to supportbrowserslist
用于告诉您要支持哪些浏览器(及其版本)
All those properties are used by either npm
or other tools that we can use.
npm
或我们可以使用的其他工具都使用了所有这些属性。
属性分类 (Properties breakdown)
This section describes the properties you can use in detail. I refer to “package” but the same thing applies to local applications which you do not use as packages.
本节介绍可以详细使用的属性。 我指的是“软件包”,但同样的情况适用于您不用作软件包的本地应用程序。
Most of those properties are only used on the https://www.npmjs.com/, other by scripts that interact with your code, like npm
or others.
这些属性中的大多数仅在https://www.npmjs.com/上使用 ,其他属性则通过与您的代码进行交互的脚本(例如npm
或其他)来使用。
name
(name
)
Sets the package name.
设置程序包名称。
Example:
例:
"name": "test-project"
The name must be less than 214 characters, must not have spaces, it can only contain lowercase letters, hyphens (-
) or underscores (_
).
名称必须少于214个字符,不能包含空格,只能包含小写字母,连字符( -
)或下划线( _
)。
This is because when a package is published on npm
, it gets its own URL based on this property.
这是因为当程序包在npm
上发布时,它会基于此属性获得自己的URL。
If you published this package publicly on GitHub, a good value for this property is the GitHub repository name.
如果您在GitHub上公开发布了此软件包,则此属性的一个不错的选择就是GitHub存储库名称。
author
(author
)
Lists the package author name
列出软件包作者名称
Example:
例:
{
"author": "Flavio Copes <flavio@flaviocopes.com> (https://flaviocopes.com)"
}
Can also be used with this format:
也可以使用以下格式:
{
"author": {
"name": "Flavio Copes",
"email": "flavio@flaviocopes.com",
"url": "https://flaviocopes.com"
}
}
contributors
(contributors
)
As well as the author, the project can have one or more contributors. This property is an array that lists them.
除作者外,该项目可以有一个或多个贡献者。 此属性是列出它们的数组。
Example:
例:
{
"contributors": [
"Flavio Copes <flavio@flaviocopes.com> (https://flaviocopes.com)"
]
}
Can also be used with this format:
也可以使用以下格式:
{
"contributors": [
{
"name": "Flavio Copes",
"email": "flavio@flaviocopes.com",
"url": "https://flaviocopes.com"
}
]
}
bugs
(bugs
)
Links to the package issue tracker, most likely a GitHub issues page
链接到软件包问题跟踪器,最有可能是GitHub问题页面
Example:
例:
{
"bugs": "https://github.com/flaviocopes/package/issues"
}
homepage
(homepage
)
Sets the package homepage
设置软件包主页
Example:
例:
{
"homepage": "https://flaviocopes.com/package"
}
version
(version
)
Indicates the current version of the package.
指示软件包的当前版本。
Example:
例:
"version": "1.0.0"
This property follows the semantic versioning (semver) notation for versions, which means the version is always expressed with 3 numbers: x.x.x
.
此属性遵循版本的语义版本控制(符号)符号,这表示版本始终以3个数字表示: xxx
。
The first number is the major version, the second the minor version and the third is the patch version.
第一个数字是主要版本,第二个数字是次要版本,第三个数字是补丁程序版本。
There is a meaning in these numbers: a release that only fixes bugs is a patch release, a release that introduces backward-compatible changes is a minor release, a major release can have breaking changes.
这些数字的含义是:仅修复错误的发行版是补丁发行版,引入向后兼容更改的发行版是次要发行版,主要发行版可能具有重大更改。
license
(license
)
Indicates the license of the package.
指示软件包的许可证。
Example:
例:
"license": "MIT"
keywords
(keywords
)
This property contains an array of keywords that associate with what your package does.
此属性包含与包功能相关联的关键字数组。
Example:
例:
"keywords": [
"email",
"machine learning",
"ai"
]
This helps people find your package when navigating similar packages, or when browsing the https://www.npmjs.com/ website.
这有助于人们在浏览相似的软件包或浏览https://www.npmjs.com/网站时找到您的软件包。
description
(description
)
This property contains a brief description of the package
此属性包含软件包的简短描述
Example:
例:
"description": "A package to work with strings"
This is especially useful if you decide to publish your package to npm
so that people can find out what the package is about.
如果您决定将软件包发布到npm
以便人们可以了解该软件包的内容,这将特别有用。
repository
(repository
)
This property specifies where this package repository is located.
此属性指定此程序包存储库所在的位置。
Example:
例:
"repository": "github:flaviocopes/testing",
Notice the github
prefix. There are other popular services baked in:
注意github
前缀。 其他受欢迎的服务还包括:
"repository": "gitlab:flaviocopes/testing",
"repository": "bitbucket:flaviocopes/testing",
You can explicitly set the version control system:
您可以显式设置版本控制系统:
"repository": {
"type": "git",
"url": "https://github.com/flaviocopes/testing.git"
}
You can use different version control systems:
您可以使用不同的版本控制系统:
"repository": {
"type": "svn",
"url": "..."
}
main
(main
)
Sets the entry point for the package.
设置包的入口点。
When you import this package in an application, that’s where the application will search for the module exports.
在应用程序中导入此程序包时,应用程序将在该位置搜索模块导出。
Example:
例:
"main": "src/main.js"
private
(private
)
if set to true
prevents the app/package to be accidentally published on npm
如果设置为true
防止应用程序/软件包在npm
上意外发布
Example:
例:
"private": true
scripts
(scripts
)
Defines a set of node scripts you can run
定义一组可以运行的节点脚本
Example:
例:
"scripts": {
"dev": "webpack-dev-server --inline --progress --config build/webpack.dev.conf.js",
"start": "npm run dev",
"unit": "jest --config test/unit/jest.conf.js --coverage",
"test": "npm run unit",
"lint": "eslint --ext .js,.vue src test/unit",
"build": "node build/build.js"
}
These scripts are command line applications. You can run them by calling npm run XXXX
or yarn XXXX
, where XXXX
is the command name. Example: npm run dev
.
这些脚本是命令行应用程序。 您可以通过调用npm run XXXX
或yarn XXXX
来运行它们,其中XXXX
是命令名称。 示例: npm run dev
。
You can use any name you want for a command, and scripts can do literally anything you want.
您可以为命令使用任何名称,脚本可以执行任何您想要的操作。
dependencies
(dependencies
)
Sets a list of npm
packages installed as dependencies.
设置作为依赖项安装的npm
软件包列表。
When you install a package using npm or yarn:
使用npm或yarn安装软件包时:
npm install <PACKAGENAME>
yarn add <PACKAGENAME>
that package is automatically inserted in this list.
该软件包将自动插入此列表中。
Example:
例:
"dependencies": {
"vue": "^2.5.2"
}
devDependencies
(devDependencies
)
Sets a list of npm
packages installed as development dependencies.
设置作为开发依赖项安装的npm
软件包列表。
They differ from dependencies
because they are meant to be installed only on a development machine, not needed to run the code in production.
它们不同于dependencies
因为它们只能安装在开发机器上,而无需在生产环境中运行代码。
When you install a package using npm or yarn:
使用npm或yarn安装软件包时:
npm install --dev <PACKAGENAME>
yarn add --dev <PACKAGENAME>
that package is automatically inserted in this list.
该软件包将自动插入此列表中。
Example:
例:
"devDependencies": {
"autoprefixer": "^7.1.2",
"babel-core": "^6.22.1"
}
engines
(engines
)
Sets which versions of Node.js and other commands this package/app work on
设置此程序包/应用程序可处理的Node.js版本和其他命令
Example:
例:
"engines": {
"node": ">= 6.0.0",
"npm": ">= 3.0.0",
"yarn": "^0.13.0"
}
browserslist
(browserslist
)
Is used to tell which browsers (and their versions) you want to support. It’s referenced by Babel, Autoprefixer, and other tools, to only add the polyfills and fallbacks needed to the browsers you target.
用于告诉您要支持哪些浏览器(及其版本)。 Babel,Autoprefixer和其他工具引用了它,仅将所需的polyfill和fallback添加到目标浏览器。
Example:
例:
"browserslist": [
"> 1%",
"last 2 versions",
"not ie <= 8"
]
This configuration means you want to support the last 2 major versions of all browsers with at least 1% of usage (from the CanIUse.com stats), except IE8 and lower.
此配置意味着您要支持所有浏览器的最后2个主要版本,并且至少要使用1%的使用率(来自CanIUse.com统计信息),但IE8和更低版本除外。
(see more)
( 查看更多 )
特定于命令的属性 (Command-specific properties)
The package.json
file can also host command-specific configuration, for example for Babel, ESLint, and more.
package.json
文件还可以托管特定于命令的配置,例如Babel,ESLint等。
Each has a specific property, like eslintConfig
, babel
and others. Those are command-specific, and you can find how to use those in the respective command/project documentation.
每个属性都有一个特定的属性,例如eslintConfig
, babel
和其他属性。 它们是特定于命令的,您可以在相应的命令/项目文档中找到如何使用它们。
套件版本 (Package versions)
You have seen in the description above version numbers like these: ~3.0.0
or ^0.13.0
. What do they mean, and which other version specifiers can you use?
在上面的描述中,您已经看到类似以下的版本号: ~3.0.0
或^0.13.0
。 它们是什么意思,您还可以使用哪些其他版本说明符?
That symbol specifies which updates you package accepts, from that dependency.
该符号指定您的软件包从该依赖项接受哪些更新。
Given that using semver (semantic versioning) all versions have 3 digits, the first being the major release, the second the minor release and the third is the patch release, you have these rules:
鉴于使用semver(语义版本控制),所有版本都有3位数字,第一个是主要版本,第二个是次要版本,第三个是补丁版本,因此您具有以下规则:
~
: if you write~0.13.0
, you want to only update patch releases:0.13.1
is ok, but0.14.0
is not.~
:如果你写~0.13.0
,你只想更新补丁发布:0.13.1
是好的,但0.14.0
不是。^
: if you write^0.13.0
, you want to update patch and minor releases:0.13.1
,0.14.0
and so on.^
:如果你写^0.13.0
,要更新补丁和次要版本:0.13.1
,0.14.0
等等。*
: if you write*
, that means you accept all updates, including major version upgrades.*
:如果您输入*
,则表示您接受所有更新,包括主要版本升级。>
: you accept any version higher than the one you specify>
:您接受比您指定的版本更高的任何版本>=
: you accept any version equal to or higher than the one you specify>=
:您接受等于或高于您指定的版本的任何版本<=
: you accept any version equal or lower to the one you specify<=
:您接受等于或低于您指定的版本的任何版本<
: you accept any version lower to the one you specify<
:您接受低于指定版本的任何版本
There are other rules, too:
还有其他规则:
- no symbol: you accept only that specific version you specify 无符号:您仅接受指定的特定版本
latest
: you want to use the latest version availablelatest
:您想使用可用的最新版本
and you can combine most of the above in ranges, like this: 1.0.0 || >=1.1.0 <1.2.0
, to either use 1.0.0 or one release from 1.1.0 up, but lower than 1.2.0.
并且您可以在范围内组合以上大部分内容,例如: 1.0.0 || >=1.1.0 <1.2.0
1.0.0 || >=1.1.0 <1.2.0
,以使用1.0.0或从1.1.0开始的一个发行版,但低于1.2.0。