创建 Node.js 的配置文件 package.json
npm init -ypackage.json 文件配置说明
| 配置 | 说明 | 示例 |
|---|---|---|
| name | 指定项目的名称，必须是小写字母，可以包含字母、数字、连字符（-）或下划线（_），不能有特殊字符，除非是 scoped 包名使用@符号 | { "name": "my-project" } |
| version | 指定项目的版本号。它遵循 语义版本控制（SemVer） 规范，格式为 MAJOR.MINOR.PATCH，每个部分都是数字。 稳定版本："version": "1.0.0" | { "version": "1.2.3" } |
| description | 简要描述项目或包的功能和目的。 | { "description": "" } |
| main | 用于指定项目的入口文件，通常是模块的主文件路径。如果没有显式指定 main，Node.js 会查找默认的文件 index.js。主要用于CommonJS的旧环境。 | { "main": "index.js" // 指向根目录的文件 "main": "dist/main.mjs" // 使用 ES 模块 "main": "dist/index.ts" // 使用 TypeScript 文件 } |
| module | 如果你的项目包含了同时支持 CommonJS 和 ES 模块格式的代码，module 字段通常用于指定适合 ESM 环境的入口 | { "main": "dist/index.js", "module": "dist/index.mjs" } |
| exports | 为不同的环境、路径和模块系统提供不同的模块导出。 | { "exports": { "import": "./esm/index.js", // 用于支持 ES Modules 的环境 "require": "./cjs/index.js", // 用于 CommonJS 环境 ".": "./index.js" // 默认导出 } } |
| imports | 是 exports 的配套功能（Node.js 16 和后续版本中引入），用于在 ESM 环境中提供特定模块路径的映射。通过 imports，你可以定义模块路径的别名、重定向以及其他解析规则。 | // 导入 my-lib/* 的代码都会被映射到 ./src/my-lib/* 下，而导入 utils/* 的代码会映射到 ./src/utils/* { "imports": { "my-lib/*": "./src/my-lib/*", "utils/*": "./src/utils/*" } } import { feature } from 'my-lib/feature'; |
| scripts | 用于自定义 npm 脚本。这些脚本可以通过 npm run <script-name> 来执行，允许你自动化常见任务，如构建、测试、发布等。 | { "scripts": { "start": "node server.js", "test": "mocha test/**/*.js" } } |
| keywords | 用于指定一组关键字，这些关键字可以帮助其他开发者更容易地找到你的项目或包，尤其是在发布到 npm 等包管理平台时。 | { "keywords": [ "utility", "javascript", "library", "tools" ] } |
| author | 用于指定项目或包的作者。通常这个字段包含作者的名称、电子邮件和网址等信息，以便其他人能够联系到作者，或了解项目的维护者是谁。 | { { |
| license | 用于指定项目的许可类型。它说明了项目的使用、复制、修改和分发的规则。常见的开源许可协议包括 MIT、Apache-2.0、GPL 等。 | { "license": ["MIT", "Apache-2.0"] } |
| type | 用于指定包的模块类型，它主要影响 Node.js 如何解析项目中的文件。 module：指示项目使用 ES 模块（支持 import/export）。 commonjs：指示项目使用 CommonJS 模块（支持 require/module.exports）。 默认是 commonjs，但可以通过 .mjs 和 .cjs 来混合使用这两种模块类型。 | { "type": "module" } |
| types | 用于 TypeScript 项目中，指示该项目的类型定义文件位置。（类型定义是一种帮助 TypeScript 理解 JavaScript 代码结构的机制）。 | { "types": "lib/index.d.ts" } |
| typings | 同 types 相似，官方推荐使用types。 | { "typings": "lib/index.d.ts" } |
| homepage | 指定包的主页或相关网站的 URL。这通常是指向项目的官方网站、文档、GitHub 仓库等信息的链接。 | { "homepage": "https://github.com/username/project-name" } |
| bugs | 用于指定与包相关的错误报告和问题追踪的 URL。当你希望用户报告 bug 或提出问题时请使用此配置。 | { "bugs": { "url": "https://github.com/username/project-name/issues", "email": "bugs@example.com" } } |
| man | 用于指定与包相关的手册页文件（man pages）的路径。当你的项目包含命令行工具或者实用程序，且希望在安装时自动安装手册页，请使用此配置 | { "man": [ "man/my-command.1" ] } |
| repository | 用于指定开源包的版本控制系统（如 Git）的仓库地址。这个字段提供了包的源码仓库位置用于让其他人访问源码，通常是 GitHub、GitLab 或其他托管平台上的仓库 URL。 | { "repository": { "type": "git", "url": "https://github.com/username/project-name.git" } } |
| contributors | 用于指定参与项目的贡献者信息。这个字段可以包含一个或多个贡献者的姓名、电子邮件地址以及其他联系信息。它通常用于开源项目中，以便记录对项目做出贡献的开发者或其他成员。 | { "contributors": [ "John Doe", "Jane Smith" ] } |
| funding | 用于指定如何支持项目的资金来源，特别是对于开源项目。它可以包含一个 URL 或多个 URL，这些链接指向可以帮助资助项目的资源，比如赞助页面、捐款平台、支持者名单等。 | { "funding": "https://github.com/sponsors/username" } |
| dependencies | 用于列出项目运行时（生产环境）所需的所依赖的其他包或模块。通常包括你在项目中引用的外部库和工具。它们会在执行 npm install 时被安装。 | // 远程npm仓库 { "dependencies": { "express": "^4.17.1", "lodash": "^4.17.20" } } // GitHub 仓库 URL 作为依赖 { "dependencies": { "my-package": "https://github.com/username/my-package.git" } } // 本地项目路径作为依赖 { "dependencies": { "my-local-package": "file:./path/to/local-package" } } |
| devDependencies | 用于列出项目开发过程中所需的依赖包。这些依赖仅在开发、测试和构建过程中使用，而在生产环境中并不需要。 | { "devDependencies": { "webpack": "^5.0.0", "babel-cli": "^6.0.0", "eslint": "^7.10.0" } } |
| peerDependencies | 用于指定你开发的公共包与其他包的兼容性。告诉使用你包的开发者，这个包与哪些包的版本兼容。 | // 告诉使用你的包的开发者需要与 react 的版本 16.x.x 或 17.x.x 兼容。 { "peerDependencies": { "react": "^16.0.0 || ^17.0.0" } } |
| optionalDependencies | 用于列出项目的可选依赖包。这些依赖是“可选的”，意味着如果安装这些包失败，npm 不会视其为错误，也不会阻止安装过程。optionalDependencies 常用于那些不是项目运行所必需的包，但如果安装成功，将为项目提供额外功能或增强功能。 | { "optionalDependencies": { "fsevents": "^2.1.3", "node-sass": "^4.14.1" } } |
| bundleDependencies、bundledDependencies | 用于指定哪些依赖包应该与项目一起打包并包含在发布包中。它主要用于将某些依赖打包到项目的发布版中，以便在项目发布后，这些依赖仍然可用，即使安装者没有显式安装（dependencies ）这些依赖。 | { "bundleDependencies": [ "lodash", "moment" ] } |
| dependenciesMeta | 相对较新的字段，作用于dependencies用于提供有关项目依赖的附加元数据，尤其是对特定依赖的配置和行为的定制化。该字段允许你为依赖包提供一些额外的属性或指示，以控制它们在安装过程中的某些行为。 | { "dependencies": { "lodash": "^4.17.21", "axios": "^0.21.1" }, "dependenciesMeta": { "lodash": { "optional": true // 设置为可选的依赖，即使安装失败也不会中断安装过程 }, "axios": { "optional": false // 设置为必需的依赖，安装时必须成功。 } } } |
| peerDependenciesMeta | 同dependenciesMeta效果一样，作用于peerDependencies。 | { "peerDependencies": { "react": "^16.8.0" }, "peerDependenciesMeta": { "react": { "optional": true } } } |
| optionalDependenciesMeta | 同dependenciesMeta效果一样，作用于optionalDependencies。 | { "optionalDependencies": { "fsevents": "^2.1.3" }, "optionalDependenciesMeta": { "fsevents": { "optional": true } } } |
| engines | 用于指定你的项目所支持的 Node.js 版本或 npm 运行时环境的版本要求。 | { "engines": { "node": ">=14.0.0 <16.0.0", // 项目只支持 Node.js 版本在 14.x.x 至 15.x.x 之间 "npm": ">=6.0.0" // 要求 npm 版本不能低于 6.0.0 } } |
| private | 用来标记一个项目是否为私有项目。设置为 true 时，npm会将这个项目视为私有项目，并禁止将其发布到 npm 仓库中心上。这个选项通常用于库或工具开发，防止意外发布项目。 | { "private": true } |
| files | 用于控制哪些文件应该被包括在发布到 npm 仓库中心的包中，哪些文件应该被排除。files 是一个数组，每个元素都是一个字符串，表示要发布的文件或目录的路径。路径是相对于 package.json 文件的位置的。 | // npm 只会发布 bin/、lib/ 目录和 README.md 文件，其他文件会被忽略 { |
| .npmignore | .npmignore 文件用于排除不需要的文件。和 files 的作用相反。如果你的 package.json 中有 files 字段，.npmignore 文件将不会生效 | |
| config | 用于存储项目相关的配置项的对象。它可以用来定义在 npm 脚本中访问的自定义配置参数。这些配置项不会影响项目的发布内容，而是帮助开发者在项目的构建或运行过程中传递和访问配置数据。 | { "name": "my-package", "version": "1.0.0", "config": { "apiUrl": "https://api.example.com", "port": 8080 }, "scripts": { "start": "node server.js", "build": "webpack --config webpack.config.js", "print-api-url": "echo $npm_package_config_apiUrl" // linux 使用 $符号 "print-api-url2": "echo %npm_package_config_apiUrl%" // windows 使用 %%符号 } } |
| pack | npm pack 命令通常用于创建一个项目的发布包，但并不将其上传到 npm 中心仓库，而是生成一个 tarball （.tgz）文件，你可以选择何时发布它。 | // 打包 npm pack // 在本地测试包 npm install ./my-package-1.0.0.tgz |
| prepack | prepack 是一个 npm 生命周期脚本，prepack 脚本在执行 npm pack、npm publish 时(同时)，会被自动执行。prepack 代替了 prepublish 和 prepublishOnly。 | // 在发布前先编译 { "scripts": { "prepack": "tsc" } } |
| postpack | postpack 是一个 npm 生命周期脚本，它会在 npm pack 命令执行后触发，通常用于在创建包的过程中执行一些后处理任务。postpack 在打包操作完成后触发，可以用来执行一些清理工作、记录日志、修改包内容或其他必要的操作。 | |
| prepare | 用于在运行 npm install 或 npm publish 时执行构建、编译、清理等操作。prepare 代替了 prepublish 和 prepublishOnly。 | { "scripts": { "prepare": "tsc" } } |
| postpublish | postpublish 是一个 npm 生命周期脚本，它会在 npm publish 命令执行之后触发。 | { "scripts": { "postpublish": "echo '发布成功!'" } } |
| publishConfig | 帮助你控制 npm publish 发布过程中的细节，例如发布的目标注册表、发布的标签、或者发布时的其他元数据。 registry：如果你想将包发布到私有的 npm 注册表，而不是默认的公共 npm 注册表。 tag：在发布新版本时，tag 字段用于指定版本的标签。例如，npm publish --tag beta 将包发布为 beta 标签。 access: 用于指定包的可访问性。它控制谁可以安装该包，可以设置为 public（公开）或 restricted（私有）。 directory: 如果你希望指定某个子目录作为发布目录（而不是整个项目的根目录）。 | { "name": "my-package", "version": "1.0.0", "publishConfig": { "registry": "https://my-private-registry.com", "tag": "next", "access": "public" } } |
| binary | binary 是一个非标准字段，它通常用于描述一个包包含的二进制文件或二进制依赖项的相关信息。这个字段可以帮助自动化工具或脚本识别和处理与包相关的二进制资源，特别是在发布或安装过程中。 | { "name": "example-package", "version": "1.0.0", "binary": { "module_name": "example-bin", "module_path": "./bin", "version": "1.0.0", "host": "https://example.com/binaries/" } } |
| preinstall | 用于在 npm install 执行之前运行某些自定义脚本。 | // 安装依赖之前检查是否安装了某个全局工具（比如 typescript） { "scripts": { "preinstall": "echo 'Running preinstall tasks...'; npm install -g typescript" } } |
| postinstall | 用于在 npm install 执行之后运行某些自定义脚本。 | // 安装依赖时需要在完成安装后执行构建脚本 { "scripts": { "postinstall": "npm run build" } } |
| pretest | 用于在 npm test 执行之前运行某些自定义脚本。 | { "scripts": { "pretest": "npm run build", "test": "jest" } } |
| posttest | 用于在 npm test 执行之后运行某些自定义脚本。 | // 在测试完成后生成一个测试报告 { "scripts": { "test": "jest", "posttest": "npm run generate-report" } } |
| preferGlobal | 用于指示包是否应当在全局环境下安装，而不是局部安装。适用于你要开发一个发布到 npm 仓库中心的工具包。 | { "preferGlobal": true } |
| bin | 用于指定模块中可执行文件的路径。这个字段主要用于当你发布一个包，并希望它包含一些可执行命令时。它允许你指定在安装该模块时将可执行文件链接到 node_modules/.bin 中的路径。 | // 模块被安装后，就会把my-command变成一个命令，命令执行./bin/my-command.js文件中的内容 { "name": "my-package", "version": "1.0.0", "bin": { "my-command": "bin/my-command.js" } } // ./bin/my-command.js 文件中的内容： #!/usr/bin/env node console.log('This is my command!'); // 然后在项目根目录终端使用命令，把自己写的命令挂载到全局命令中 npm link // 然后就可以使用 my-command 命令，执行 bin/my-command.js 文件中的内容 |
| resolutions | 用于确保项目中的所有依赖使用特定版本的包，从而避免版本冲突或不兼容的依赖版本。Yarn 作为包管理器时。 | // 无论 package-a 和 package-b 依赖于 lodash 的哪个版本，resolutions 字段都强制要求项目中所有地方使用 lodash 版本 4.17.21。 { "name": "my-project", "version": "1.0.0", "dependencies": { "package-a": "^1.0.0", "package-b": "^1.0.0" }, "resolutions": { "lodash": "4.17.21" } } |
| overrides | 用于确保项目中的所有依赖使用特定版本的包，从而避免版本冲突或不兼容的依赖版本。npm 官方支持。 | // // 无论 package-a 和 package-b 依赖于 lodash 的哪个版本，overrides 字段都强制要求项目中所有地方使用 lodash 版本 4.17.21。 { "name": "my-project", "version": "1.0.0", "dependencies": { "package-a": "^1.0.0", "package-b": "^1.0.0" }, "overrides": { "lodash": "4.17.21" } } |
| os | 指定该包或项目适用的操作系统。这个字段的目的是让某些包在特定的操作系统上才被安装或使用，从而避免在不兼容的环境中安装或运行不支持的代码。 darwin: 用于 macOS 系统。 | { "name": "my-package", "version": "1.0.0", "os": ["darwin", "linux"] } |
| cpu | 指定该包的支持 CPU 架构。这使得你可以限制包的安装和运行只在特定的 CPU 架构上，类似于 os 字段，它帮助控制包在哪些硬件环境下被安装和运行。 x64: 64 位的 x86 架构（常见的桌面计算机和服务器架构，如 Intel 和 AMD 处理器）。 | { "name": "my-package", "version": "1.0.0", "cpu": ["x64", "arm64"] } |
| lockfileVersion | lockfileVersion 是一个用于标识 package-lock.json 文件格式版本的字段。帮助 npm 在处理 package-lock.json 时确保正确的版本解析，特别是在版本升级和跨版本兼容性方面。lockfileVersion 会随着 npm 的版本变化而变化，例如 1 是 npm 5.x 的格式，2 是 npm 7.x 的格式，3 是 npm 8.x 的格式。 | { "name": "my-project", "version": "1.0.0", "lockfileVersion": 3 } |
| workspaces | 用于管理多包仓库（Monorepo）结构的字段。它允许你在一个单独的 npm 项目中管理多个子包（或称为工作空间），使得你可以在一个统一的代码库中同时管理和发布多个模块或包。 | // 将 packages 和 libs 目录下的所有子包作为工作空间 { "workspaces": [ "packages/*", "libs/*" ] } |
| deprecated | 用于标记一个包或模块已不再推荐使用。这通常是由包的维护者添加的，表示该包已经过时，可能存在问题，或者不再继续维护。 | { "name": "old-package", "version": "1.0.0", "deprecated": "This package is no longer maintained. Please use 'new-package' instead." } |
| dist | 包的分发信息。在包发布到 npm registry 后，npm 会自动为该包生成 dist 字段，并将其与包的 tarball、shasum 和 integrity 等信息一起存储。开发者通常不会手动添加 dist 字段，因为 npm 会自动处理这些信息。 | { "name": "my-package", "version": "1.0.0", "dist": { "tarball": "https://registry.npmjs.org/my-package/-/my-package-1.0.0.tgz", "shasum": "d41d8cd98f00b204e9800998ecf8427e", "integrity": "sha512-XXXXXXXXXXXXXXXXXXXXXXXXXXX" } } |
| sideEffects | 用于优化 JavaScript 模块的打包过程，尤其是在使用诸如 Webpack 这样的打包工具时。它告诉打包工具哪些模块或文件没有副作用，从而可以在树摇（Tree Shaking）过程中安全地移除未使用的代码。 false：整个项目中没有副作用，为使用的代码可以被安全的移除。 true：所有文件都包含副作用。 | { // 只有下面配置的文件有副作用 { |
| browser | 用于指定在浏览器环境下替代 Node.js 环境中的某些模块或功能。这通常用于开发同时支持 Node.js 和浏览器的库或模块，确保在浏览器中能够使用适当的替代模块或文件。 | // 假设你有一个包，它在 Node.js 中使用了 fs 和 path 模块，而这些模块在浏览器中并不可用。你可以使用 browser 字段来告诉打包工具（如 Webpack 或 Rollup）使用不同的实现。 { "name": "my-library", "version": "1.0.0", "browser": { "fs": false, // 在浏览器环境中，禁用 'fs' 模块 "path": "./browser/path.js" // 在浏览器环境中，使用自定义的 'path.js' 替代 'path' 模块 } } |
| prettier | 用于自动格式化代码，使代码风格统一，符合指定的规则。Prettier 支持多种编程语言（如 JavaScript、TypeScript、HTML、CSS、JSON 等），并且可以与各种编辑器（如 VS Code、Sublime Text 等）以及构建工具（如 Webpack、Gulp 等）集成，自动格式化代码。 semi：是否在每行代码末尾加分号，默认为 true。设置为 false 表示不加分号。 | { "name": "my-project", "version": "1.0.0", "prettier": { "semi": true, // 使用分号 "singleQuote": false, // 使用双引号 "tabWidth": 4, // 缩进为 2 个空格 "trailingComma": "all" // 在多行对象或数组最后一个元素后添加逗号 } } |
| directories | 用于指定项目中的目录结构。它主要用于指定项目中需要特别关注的目录，通常是用于某些工具或发布工具（如 npm）了解项目的结构，或者用于决定要包含哪些文件。 lib：指定项目的库文件目录，通常是源代码所在的目录。 bin：指定包含可执行文件的目录。 test：指定项目的测试文件目录。 doc：指定项目的文档目录。 man：指定手册页目录。 | { "name": "my-package", "version": "1.0.0", "directories": { "lib": "src", "bin": "bin", "test": "tests", "doc": "docs" } } |
