package.json 备忘清单

本快速参考备忘清单是您需要了解的关于 package.json 文件中所需内容的全部内容。 它必须是实际的 JSON，而不仅仅是 JavaScript 对象字面量。

• npm 文档 (npmjs.com)
• yarnpkg 文档 (yarnpkg.com)
• packages 文档 (nodejs.org)
• npm 备忘清单(速查表) (jaywcjlove.github.io)

{
  "version": "1.0.0"
}

包的当前版本，严格遵循 Semantic Versioning 2.0.0 语义化版本规范。

• 不要使用和 Node.js 核心模块相同的名字。
• 不要在名字里包含 js 或者 node 单词。
• 短小精悍，让人看到名字就大概了解包的功能，记住它也会被用在 require() 调用里。
• 保证名字在 npm registry 里是唯一的。
• name 和 version 字段一起用于创建唯一ID

如果没有 name 和version 字段，您的包将无法安装

{
  "description": "我的包的概要简短描述"
}

帮助使用者了解包的功能的字符串，包管理器也会把这个字符串作为搜索关键词。

{
  "keywords": [
    "short", "relevant", "keywords"
  ]
}

一个字符串数组，当在包管理器里搜索包时很有用。

{
  "homepage": "https://your-package.org"
}

是包的项目主页或者文档首页。

{
  "bugs": "https://github.com/user/repo/issues"
}

问题反馈系统的 URL，或者是 email 地址之类的链接。用户通过该途径向你反馈问题。

项目的维护者。

{
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "http://your-x.com"
  },
  "author": "Your Name <[email protected]> (http://your-x.com)"
}

作者信息，一个人。

{
  "files": [
    "filename.js",
    "directory/",
    "glob/*.{js,json}"
  ]
}

项目包含的文件，可以是单独的文件、整个文件夹，或者通配符匹配到的文件。

{
  "main": "filename.js"
}

项目的入口文件。

{
  "man": "./man/doc.1",
  "man": ["./man/doc.1", "./man/doc.2"]
}

项目的入口文件。

{
  "directories": {
    "lib": "path/to/lib/",
    "bin": "path/to/bin/",
    "man": "path/to/man/",
    "doc": "path/to/doc/",
    "example": "path/to/example/"
  }
}

当你的包安装时，你可以指定确切的位置来放二进制文件、man pages、文档、例子等。

{
  "bin": "bin.js",
  "bin": {
    "命令名称": "bin/命令路径/命令名称.js",
    "other-command": "bin/other-command"
  }
}

随着项目一起被安装的可执行文件。

这是一个只在 TypeScript 中生效的字段，如果您的包有一个 main.js 文件，您还需要在 package.json 文件中指明主声明文件。 将 types 属性设置为指向 bundled 的声明文件。 例如：

{
  "types": "./lib/main.d.ts",
}

如果您的主声明文件名为 index.d.ts 并且位于包的根目录（index.js旁边），则不需要标记 types 属性，建议这样做。

pkg.module 将指向具有 ES2015 模块语法的模块，但仅指向目标环境支持的语法功能。 完整的描述在这里。

{
  "module": "dist/my-package.esm.js"
}

支持：rollup, webpack

"browser": {
    "module-a": "./shims/module-a.js",
    "./server/only.js": "./shims/client-only.js"
}

字段由模块作者提供，作为 JavaScript 包或组件工具的提示，用于打包模块以供客户端使用。 提案就在这里。

{
  "name": "mod",
  "exports":{
    ".": "./lib/index.js",
    "./lib/*": "./lib/*.js"
  }
}

使用最新的 exports 字段导出，可规避 main 字段局限性 具体参考

{
  "name": "mod",
  "exports": {
    ".": "./index.js",
    "./sub": "./src/sub.js"
  }
}

导入

import sub from "mod/sub"

{
  "exports": {
    ".": "./dist/index.js"
  }
}

简写

{
  "exports": "./dist/index.js"
}

{
  "main": "./index.js",
  "exports": "./index.js"
} 

如果同时出现 main 和 exports 字段，只会读取 exports 字段

脚本是定义自动化开发相关任务的好方法，比如使用一些简单的构建过程或开发工具。 在 scripts 字段里定义的脚本，可以通过 yarn run <script> 命令来执行。 例如，下面 build-project 脚本可以通过 yarn run build-project 调用，并执行 node build-project.js。

{
  "scripts": {
    "build-project": "node build-project.js"
  }
}

有一些特殊的脚本名称。 如果定义了 preinstall 脚本，它会在包安装前被调用。 出于兼容性考虑，install、postinstall 和 prepublish 脚本会在包完成安装后被调用。

start 脚本的默认值为 node server.js。

参考文档：npm docs

{
  "config": {
    "port": "8080"
  }
}

配置你的脚本的选项或参数。

{
  "scripts": {
    "run": "echo $npm_package_config_port"
  }
}

配置中的键作为环境变量公开给脚本(scripts)。

{
  "devDependencies": {
    "package-2": "^0.4.2"
  }
}

这些是只在你的包开发期间需要，但是生产环境不会被安装的包。

{
  "overrides": {
    "foo": "1.0.0"
  }
}

对依赖项的依赖项进行特定更改，例如用已知的安全问题替换依赖项的版本

{
  "peerDependencies": {
    "package-3": "^2.7.18"
  }
}

平行依赖允许你说明你的包和其他包版本的兼容性。添加可选设置以消除丢失的对等依赖性警告，#6671 。

{
  "optionalDependencies": {
    "package-5": "^1.6.1"
  }
}

可选依赖可以用于你的包，但不是必需的。如果可选包没有找到，安装还可以继续。

{
  "bundledDependencies": [
    "package-4"
  ]
}

打包依赖是发布你的包时将会一起打包的一个包名数组。

{
  "peerDependenciesMeta": {
    "node-sass": {
      "optional": true
    },
    "sass": {
      "optional": true
    },
    "fibers": {
      "optional": true
    }
  }
}

它允许对等依赖项标记为可选

{
  "os": ["darwin", "linux"],
  "os": ["!win32"]
}

此选项指定你的包的操作系统兼容性，它会检查 process.platform。

{
  "cpu": ["x64", "ia32"],
  "cpu": ["!arm", "!mips"]
}

使用这个选项指定你的包将只能在某些 CPU 体系架构上运行，这会检查 process.arch。

{
  "private": true
}

如果你不想你的包发布到包管理器(npm 或者 私有包管理)，设置为 true。

如果你的包只允许给定依赖的一个版本，你想强制和命令行上 yarn install --flat 相同的行为，把这个值设为 true。

{
  "flat": true
}

请注意，如果你的 package.json 包含 "flat": true 并且其它包依赖你的包 (比如你在构建一个库，而不是应用)， 其它那些包也需要在它们的 package.json 加上 "flat": true，或者在命令行上用 yarn install --flat 安装。