package.json的新手指南

前端小工
333 阅读5分钟

如果你用JavaScript工作，或者你曾经与一个JavaScript项目、Node.js或一个前端项目互动，你肯定见过package.json 。

那是做什么用的？你应该知道些什么，你可以用它做哪些很酷的事情？

package.json 文件有点像你的项目的清单。它可以做很多事情，完全不相关。例如，它是一个工具配置的中央仓库。它也是 npm和 yarn存储它所安装的软件包的名称和版本。

文件结构

这里有一个package.json文件的例子。

它是空的!对于一个应用程序来说，package.json 文件中应该包含哪些内容并没有固定要求。唯一的要求是它要尊重JSON格式，否则它不能被试图以编程方式访问其属性的程序读取。

如果你正在构建一个Node.js包，你想通过npm ，事情就会发生根本性的变化，你必须有一套属性来帮助其他人使用它。我们将在后面看到更多关于这个的内容。

这是另一个package.json。

{
  "name": "test-project"
}

它定义了一个name 属性，它告诉人们应用的名称，或者说包的名称，它包含在这个文件所在的同一文件夹中。

这是一个更复杂的例子，我从一个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"
  ]
}

这里有很多事情要做。

  • name 设置应用程序/包的名称
  • version 表示当前的版本
  • description 是对应用程序/包的简要描述
  • main 设置应用程序的入口点
  • private 如果设置为 ，则可以防止应用程序/软件包被意外地发布到网上。true npm
  • scripts 定义了一组你可以运行的节点脚本
  • dependencies 设置一个作为依赖项安装的 包的列表npm
  • devDependencies 设置一个作为开发依赖的npm 包的列表
  • engines 设置这个包/应用程序可以在哪些版本的Node上运行
  • browserslist 用于告诉你要支持哪些浏览器（以及它们的版本）。

所有这些属性都被npm 或其他我们可以使用的工具所使用。

属性分类

本节详细描述了你可以使用的属性。我指的是 "包"，但同样的事情也适用于你不作为包使用的本地应用程序。

这些属性大部分只在www.npmjs.com/，其他的由与你的代码交互的脚本使用，如npm 或其他。

name

设置包的名称。

例如。

名称必须少于214个字符，不能有空格，只能包含小写字母、连字符（- ）或下划线（_ ）。

这是因为当一个包在npm 上发布时，它会根据这个属性获得自己的 URL。

如果你在GitHub上公开发布了这个包，那么这个属性的一个好值就是GitHub仓库的名称。

列出软件包作者的名字

例子。

{
  "author": "Flavio Copes <your@email.com> (https://flaviocopes.com)"
}

也可以用这种格式。

{
  "author": {
    "name": "Flavio Copes",
    "email": "your@email.com",
    "url": "https://flaviocopes.com"
  }
}

contributors

除了作者之外，该项目还可以有一个或多个贡献者。这个属性是一个数组，列出他们。

例子。

{
  "contributors": [
    "Flavio Copes <your@email.com> (https://flaviocopes.com)"
  ]
}

也可用于此格式。

{
  "contributors": [
    {
      "name": "Flavio Copes",
      "email": "your@email.com",
      "url": "https://flaviocopes.com"
    }
  ]
}

bugs

链接到包的问题跟踪器，很可能是GitHub问题页

例子。

{
  "bugs": "https://github.com/flaviocopes/package/issues"
}

homepage

设置软件包的主页

例子。

{
  "homepage": "https://flaviocopes.com/package"
}

version

表示软件包的当前版本。

例子。

这个属性遵循了版本的语义版本（semver）符号，这意味着版本总是用3个数字表示：x.x.x 。

第一个数字是主版本，第二个是次版本，第三个是补丁版本。

这些数字是有意义的：一个只修复bug的版本是补丁版本，一个引入了向后兼容的变化的版本是次要版本，一个主要版本可以有突破性的变化。

license

表示软件包的许可证。

例子。

keywords

这个属性包含了一个与你的包的功能相关联的关键字数组。

例子。

"keywords": [
  "email",
  "machine learning",
  "ai"
]

这有助于人们在浏览类似软件包时，或在浏览www.npmjs.com/网站时，找到你的软件包。

description

这个属性包含了包的简短描述

例子。

"description": "A package to work with strings"

如果你决定将你的包发布到npm ，这一点特别有用，这样人们就可以发现这个包是关于什么的。

repository

这个属性指定了这个软件包仓库的位置。

例子。

"repository": "github:flaviocopes/testing",

注意github 的前缀。还有其他流行的服务也被烘托出来了。

"repository": "gitlab:flaviocopes/testing",

"repository": "bitbucket:flaviocopes/testing",

你可以明确地设置版本控制体系。

"repository": {
  "type": "git",
  "url": "https://github.com/flaviocopes/testing.git"
}

你可以使用不同的版本控制体系。

"repository": {
  "type": "svn",
  "url": "..."
}

main

设置软件包的入口点。

当你在一个应用程序中导入这个包时，这就是应用程序将搜索模块出口的地方。

例如。

private

如果设置为true ，可以防止应用程序/软件包被意外地发布在npm

例子。

scripts

定义了一组你可以运行的节点脚本

例子。

"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"
}

这些脚本是命令行应用程序。你可以通过调用npm run XXXX 或yarn XXXX 来运行它们，其中XXXX 是命令名称。例如：npm run dev 。

你可以使用任何你想要的命令名称，而且脚本可以做任何你想要的事情。

dependencies

设置一个作为依赖项安装的npm 包的列表。

当你用npm或yarn安装一个包时，该包会自动插入这个列表。

npm install <PACKAGENAME>
yarn add <PACKAGENAME>

该软件包会自动插入到这个列表中。

例子。

"dependencies": {
  "vue": "^2.5.2"
}

devDependencies

设置一个作为开发依赖的npm 包的列表。

它们与dependencies 不同，因为它们只能安装在开发机器上，不需要在生产中运行代码。

当你用npm或yarn安装一个包时。

npm install --dev <PACKAGENAME>
yarn add --dev <PACKAGENAME>

该软件包会自动插入到这个列表中。

例子。

"devDependencies": {
  "autoprefixer": "^7.1.2",
  "babel-core": "^6.22.1"
}

engines

设置该软件包/应用程序可用于哪些版本的Node.js和其他命令

例子。

"engines": {
  "node": ">= 6.0.0",
  "npm": ">= 3.0.0",
  "yarn": "^0.13.0"
}

browserslist

用来告诉你要支持哪些浏览器（以及它们的版本）。它被Babel、Autoprefixer和其他工具所引用，只为你的目标浏览器添加所需的polyfills和fallbacks。

例子。

"browserslist": [
  "> 1%",
  "last 2 versions",
  "not ie <= 8"
]

这个配置意味着你要支持所有至少有1%使用量的浏览器的最后两个主要版本（来自CanIUse.com的统计），除了IE8和更低版本。

(查看更多)

命令专用属性

package.json 文件也可以承载特定命令的配置，例如Babel、ESLint等等。

每一个都有一个特定的属性，如eslintConfig ，babel 和其他。这些都是命令专用的，你可以在各自的命令/项目文档中找到如何使用这些。

包的版本

你在上面的描述中看到了这样的版本号：~3.0.0 或^0.13.0 。它们是什么意思，你还可以使用哪些版本的指定符？

该符号指定了你的软件包接受哪些更新，来自该依赖关系。

考虑到使用semver（语义版本管理），所有版本都有3位数字，第一位是主要版本，第二位是次要版本，第三位是补丁版本，你有这些规则。

  • ~: 如果你写~0.13.0 ，你想只更新补丁版本：0.13.1 可以，但0.14.0 不可以。
  • ^: 如果你写了^0.13.0 ，你要更新补丁和次要版本。0.13.1,0.14.0 ，以此类推。
  • *: 如果你写* ，这意味着你接受所有的更新，包括主要的版本升级。
  • >: 你接受比你指定的版本更高的任何版本
  • >=:您接受任何等于或高于您指定的版本
  • <=：你接受任何等于或低于你所指定的版本
  • <：你接受任何低于你指定的版本。

也有其他规则。

  • 无符号：你只接受你指定的那个特定版本
  • latest：你想使用最新的可用版本

你可以将上述大多数规则组合在一起，就像这样。1.0.0 || >=1.1.0 <1.2.0，以使用1.0.0或1.1.0以上的一个版本，但低于1.2.0。

avatar
文章
阅读
粉丝