package.json 备忘清单 === 这个快速参考备忘清单，显示了关于 package.json 文件中所需内容的全部内容。 重要字段 ---- ### 介绍 本快速参考备忘清单是您需要了解的关于 package.json 文件中所需内容的全部内容。 它必须是实际的 JSON，而不仅仅是 JavaScript 对象字面量。 - [npm 文档](https://docs.npmjs.com/files/package.json) _(npmjs.com)_ - [yarnpkg 文档](https://classic.yarnpkg.com/en/docs/package-json) _(yarnpkg.com)_ ### `name` ```json { "name": "my-awesome-package" } ``` **规则** - 必须小于或等于214个字符(包括 `@scope/` 范围包) - 不能以点（`.`）或下划线（`_`）开头 - 名称中不得包含大写字母 - 必须仅使用URL安全字符 ### `version` ```json { "version": "1.0.0" } ``` 包的当前版本，严格遵循 [Semantic Versioning 2.0.0](http://semver.org/lang/zh-CN/) 语义化版本规范。 ### Tips - 不要使用和 `Node.js` 核心模块相同的名字。 - 不要在名字里包含 `js` 或者 `node` 单词。 - 短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 `require()` 调用里。 - 保证名字在 [npm registry](https://www.npmjs.com/) 里是唯一的。 - name 和 version 字段一起用于创建唯一ID 如果没有 `name` 和`version` 字段，您的包将无法安装 ### 安装 `name` 包 ```sh yarn add [包名] # or npm install [包名] ``` 安装后存放位置 ```bash node_modules/[包名] ``` npmjs 下载地址 ```bash https://registry.npmjs.org/[包名]/-/[包名]-[version].tgz ``` 这是您的 `包` 的名称。 它在URL中使用，作为参数命令行，以及 `node_modules` 中的目录名。 信息类字段 ---- ### `description` ```json { "description": "我的包的概要简短描述" } ``` 帮助使用者了解包的功能的字符串，包管理器也会把这个字符串作为搜索关键词。 ### `license` 所有包都应该指定许可证，以便让用户了解他们是在什么授权下使用此包，以及此包还有哪些附加限制。 ```json { "license": "MIT", "license": "(MIT or GPL-3.0)", "license": "SEE LICENSE IN LICENSE_FILENAME.txt", "license": "UNLICENSED" } ``` 鼓励使用开源 [(OSI-approved)](https://opensource.org/licenses/alphabetical) 许可证，除非你有特别的原因不用它。 如果你开发的包是你工作的一部分，最好和公司讨论后再做决定。 **license字段必须是以下之一:** - 如果你使用标准的许可证，需要一个有效地 [SPDX 许可证标识](https://spdx.org/licenses/)。 - 如果你用多种标准许可证，需要有效的 [SPDX 许可证表达式2.0语法表达式](https://www.npmjs.com/package/spdx)。 - 如果你使用非标准的许可证，一个 `SEE LICENSE IN <文件名>` 字符串指向你的包里顶级目录的一个 <文件名>。 - 如果你不想在任何条款下授权其他人使用你的私有或未公开的包，一个 `UNLICENSED` 字符串。 ### `keywords` ```json { "keywords": [ "short", "relevant", "keywords" ] } ``` 一个字符串数组，当在包管理器里搜索包时很有用。 链接类字段 ---- 各种指向项目文档、issues 上报，以及代码托管网站的链接字段。 ### `homepage` ```json { "homepage": "https://your-package.org" } ``` 是包的项目主页或者文档首页。 ### `repository` ```json { "repository": { "type": "git", "url": "https://github.com/user/repo.git" }, "repository": "github:user/repo", "repository": "gitlab:user/repo", "repository": "bitbucket:user/repo", "repository": "gist:a1b2c3d4e5f" } ``` 包的实际代码所在的位置。 ### `bugs` ```json { "bugs": "https://github.com/user/repo/issues" } ``` 问题反馈系统的 URL，或者是 email 地址之类的链接。用户通过该途径向你反馈问题。 项目维护类字段 ---- ### `author` 项目的维护者。 ```json { "author": { "name": "Your Name", "email": "you@xxx.com", "url": "http://your-x.com" }, "author": "Your Name (http://your-x.com)" } ``` 作者信息，一个人。 ### `contributors` ```json { "contributors": [ { "name": "Your Friend", "email": "friend@xxx.com", "url": "http://friends-xx.com" } { "name": "Other Friend", "email": "other@xxx.com", "url": "http://other-xx.com" } ], "contributors": [ "Your Friend (http://friends-xx.com)", "Other Friend (http://other-xx.com)" ] } ``` 贡献者信息，可能很多人。 ## 文件类信息 指定包含在项目中的文件，以及项目的入口文件。 ### `files` ```json { "files": [ "filename.js", "directory/", "glob/*.{js,json}" ] } ``` 项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。 ### `main` ```json { "main": "filename.js" } ``` 项目的入口文件。 ### `man` ```json { "man": "./man/doc.1", "man": ["./man/doc.1", "./man/doc.2"] } ``` 项目的入口文件。 ### `directories` ```json { "directories": { "lib": "path/to/lib/", "bin": "path/to/bin/", "man": "path/to/man/", "doc": "path/to/doc/", "example": "path/to/example/" } } ``` 当你的包安装时，你可以指定确切的位置来放二进制文件、man pages、文档、例子等。 ### `bin` ```json { "bin": "bin.js", "bin": { "命令名称": "bin/命令路径/命令名称.js", "other-command": "bin/other-command" } } ``` 随着项目一起被安装的可执行文件。 ### `types` 这是一个只在 [TypeScript](https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html) 中生效的字段，如果您的包有一个 `main.js` 文件，您还需要在 `package.json` 文件中指明主声明文件。 将 `types` 属性设置为指向 `bundled` 的声明文件。 例如： ```json { "types": "./lib/main.d.ts", } ``` 如果您的主声明文件名为 `index.d.ts` 并且位于包的根目录（`index.js`旁边），则不需要标记 `types` 属性，建议这样做。 ## 打包包字段 ### `esnext` 完整的[提案在这里](http://2ality.com/2017/04/transpiling-dependencies-babel.html)。 简短说明： - `esnext`：ES模块中使用阶段4功能（或更旧版本）的源代码，未编译。 - `main`：指向一个CommonJS模块（或UMD模块），其 `JavaScript` 与 `Node.js` 当前可以处理的一样现代。 - 大多数 `module` 用例应该可以通过 `esnext` 处理。 - `browser` 可以通过 `esnext` 的扩展版本来处理 ```json { "main": "main.js", "esnext": { "main": "main-esnext.js", "browser": "browser-specific-main-esnext.js" } } ``` 另请参阅：[通过 npm 交付未编译的源代码](http://2ality.com/2017/06/pkg-esnext.html) ### `module` `pkg.module` 将指向具有 `ES2015` 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述[在这里](https://github.com/rollup/rollup/wiki/pkg.module)。 ```json { "module": "dist/my-package.esm.js" } ``` 支持：[rollup](https://github.com/rollup/rollup-plugin-node-resolve), [webpack](https://webpack.js.org/configuration/resolve/#resolve-mainfields) ### `browser` ```json "browser": { "module-a": "./shims/module-a.js", "./server/only.js": "./shims/client-only.js" } ``` 字段由模块作者提供，作为 `JavaScript` 包或组件工具的提示，用于打包模块以供客户端使用。 提案就[在这里](https://github.com/defunctzombie/package-browser-field-spec)。 ## 任务类字段 包里还可以包含一些可执行脚本或者其他配置信息。 ### `scripts` ```json { "scripts": { "build-project": "node build-project.js" } } ``` 脚本是定义自动化开发相关任务的好方法，比如使用一些简单的构建过程或开发工具。 在 `scripts` 字段里定义的脚本，可以通过 `yarn run