Skip to Content
Nextra 4.0 is released 🎉
笔记WebPackage.json 指南

Package.json 指南

前言

package.json 是一个用于描述和配置项目的重要文件，其中包含了许多字段和选项，可以影响项目的构建、依赖管理、脚本执行等方面。了解这些字段可以帮助开发者更好地理解和控制项目的行为。

必须属性

name

定义项目的名称，不能以”.”和”_“开头，不能包含大写字母

version

定义项目的版本号，格式为：大版本号.次版本号.修订号

描述信息

description

项目描述

keywords

项目关键词

author

项目作者

{
  "author": "<name>"
}

contributors

项目贡献者

{
  "contributors": [
    "<name>",
    "<name>"
  ]
}

homepage

项目主页地址

repository

项目代码仓库地址

bugs

项目提交问题的地址

提交问题的地址和反馈的邮箱, url通常是github中的issues页面

{
  "bugs": {
    "url": "https://github.com/karoldy/web-blog.github.io/issues",
    "email": "karoldy@163.com"
  }
}

funding

指定项目的资金支持方式和链接

{
  "funding": {
    "type": "patreon",
    "url": "https://www.patreon.com"
  }
}

依赖配置

dependencies

生产环境的依赖包

如果不使用脱字符（^），安装的版本号固定；如果使用，则能安装当前大版本的最新版本，在package-lock.json中可查看当前实际安装的版本。

devDependencies

开发环境的依赖包，例如webpack、vite、babel、ESLint等。

peerDependencies

对等依赖的作用：

  1. 减小打包体积：例如使用react开发的组件库，安装react是必不可少的，而使用组件库的开发者，本地项目肯定安装了react，因此开发的组件库中不必把react打包进去（期望项目的使用者来提供这些模块的实现）。
  2. 版本一致性：使用你的组件库的开发者需要确保他们项目中安装了与你声明的对等依赖版本兼容的包，以确保组件库正常运行。

示例：声明要使用组件库，需在项目中安装大于17.0.1版本的react

{
  "peerDependencies": {
    "react": ">17.0.1"
  }
}

peerDependenciesMeta

将对等依赖标记为可选，如果用户没有安装对等依赖，npm不会发出警告

{
  "peerDependenciesMeta": {
    "react": {
      "optional": true
    }
  }
}

bundledDependencies

声明捆绑依赖项（使用情景较少）

optionalDependencies

声明可选依赖项（使用情景较少）

engines

声明对npm或node的版本要求

{
  "engines": {
    "node": ">=8.10.3 <12.13.0",
    "npm": ">=6.9.0"
  }
}

目前对NPM来说，engines只是起一个说明的作用，即使用户安装的版本不符合要求，也不影响依赖包的安装。但使用pnpm 和 yarn安装，如果版本不符合要求会导致安装失败。

workspaces

单个代码库中统一管理多个包（monorepo），在workspaces声明目录下的package会软链到根目录的node_modules中。

声明本项目是workspaces模式

{
  "private": "true",
  "workspaces": [
    "packages/*"
  ]
}

表示所有子包都在packages文件夹下

创建子包p1

npm init -w packages/p1 -y

在node_modules/.package-lock.json中可以看到 “link”: true 链接符号信息

新建packages/p1/index.js

module.exports = "p1包"

创建子包p2

npm init -w packages/p2 -y

将子包p1添加到p2中

npm i p1 -w p2

安装，卸载等命令都是一样的，只是多了”—workspace=“参数（简写-w），用来指定在哪个包中执行命令

子包p2使用p1

const p1 = require('p1');
 
console.log('使用', p1);
 
module.exports = 'p2包'

workspaces功能与lerna类似，如果只需简单地管理多个包，workspaces足够了。lerna具有版本管理，发包提示，简化多包项目发布流程等更多功能。

脚本配置

scripts

脚本入口

scripts 配置

{
  "scripts": {
    "start": "node index.js"
  }
}

config

用于定义项目的配置项，例如设置环境变量

config 配置

{
  "config": {
    "baseUrl": "https://example.com"
  }
}

文件&目录

module（非官方字段）

指定 ES 模块入口文件

示例：当其他开发者在他们的项目中导入你的包时，会加载并执行包中的dist/index.esm.js

{
  "main": "dist/index.esm.js"
}

main

指定 CommonJS 模块或 ES 模块入口文件。如果不指定该字段，默认是根目录下的index.js

提示：从 Node.js 12.20.0 版本开始，“main” 字段也可以指定 ES 模块的入口文件

browser

指定浏览器使用的入口文件，例如umd模块。

types（非官方字段）

指定 TypeScript 类型声明文件（.d.ts 文件）的路径

exports（非官方字段）

当打包工具支持exports字段时（webpack、Rollup 等），以上main，browser，module，types四个字段都被忽略

”.” 表示默认导出

“import”: 指定了 ES module (ESM) 规范下的导出文件路径

“require”: 指定了 CommonJS 规范下的导出文件路径

“browser”: 指定了用于浏览器环境的导出文件路径

“types”: 指定了类型声明文件的路径

{
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs.js",
      "browser": "./dist/index.umd.js",
      "types": "./dist/index.d.ts"
    }
  }
}

type（非官方字段）

指定模块系统的使用方式，“commonjs”，“module”，“umd”，“json”

示例：指定模块系统为ES module模式，使用CommonJS文件时，需显式的定义为 .cjs 文件扩展名，来明确指定这些文件为 CommonJS 模块

{
  "type": "module"
}

files

指定哪些包被推送到npm服务器中

示例：只推送index.js和dist包到npm服务器

{
  "files": [
    "index.js",
    "dist"
  ]
}

可以在项目根目录新建一个.npmignore文件，说明不需要提交到npm服务器的文件，类似.gitignore。写在这个文件中的文件即便被写在files属性里也会被排除在外

bin

定义在全局安装时可执行的命令，例如构建脚手架

{
  "bin": "cli.js"
}

man

Linux 中的帮助指令（使用情景较少）

directories

定义项目目录结构的字段（使用情景较少）

发布配置

private

防止私有包发布到npm服务器，要发布到npm上设为false

preferGlobal（非官方字段）

当设置 “preferGlobal” 字段为 true 时，它表示你的包更适合以全局方式安装，而不是作为项目的依赖项进行本地安装。

这个字段的设置是为了向用户传达关于你的包的最佳使用方式的建议。它并不会直接影响包的安装方式或包管理器的行为。

publishConfig

在发布包时指定特定的配置

示例：指定包发布的注册表 URL，指定所有用户都可以访问（私有的会收费）

{
  "publishConfig": {
    "registry": "https://registry.npmjs.org/",
    "access": "public"
  }
}

os

指定你的包适用的操作系统

示例：包只适用于darwin（macOS）和 linux

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

示例：禁用win32

{
  "os": ["!win32"]
}

cpu

该配置和OS配置类似，用CPU可以更准确的限制用户的安装环境

license

指定软件的开源协议：

ISC：在所有副本中保留版权声明和许可证声明，使用者就可以拿你的代码做任何想做的事情，你也无需承担任何责任

MIT：在所有副本或主要部分中保留版权声明和许可证声明，使用者就可以拿你的代码做任何想做的事情，你也无需承担任何责任

开源协议查询地址：opensource.org/licenses/

第三方配置（非官方字段）

eslintConfig

eslint的配置，更推荐新建 .eslintrc 进行配置

使用参考：新建 .eslintrc

babel

babel的配置，更推荐新建 .babelrc 进行配置

unpkg

unpkg 是一个基于 CDN 的前端包托管服务，用于在浏览器中直接引用和加载 npm 上发布的包。

lint-staged

lint-staged是一个在Git暂存文件上运行linters的工具，通常配合gitHooks一起使用。

使用参考：配置 husky、lint-staged、@commitlint/cli

browserslist

告知支持哪些浏览器及版本，Autoprefixer常用到它

{
  "browserslist": [
    "defaults",
    "not ie < 8",
    "last 2 versions",
    "> 1%",
    "ios 7",
    "last 3 ios versions"
  ]
}

sideEffects

指示包是否具有副作用，协助Webpack，Rollup等进行tree shaking

多数情况下可以直接设置为false，这样打包工具就会自动删除未被import的代码

但是有些情况例外

  1. 有一些特定的模块文件，它们执行一些副作用操作，如注册全局事件监听器、修改全局状态等。
  2. 告诉构建工具不要将样式文件排除在无用代码消除的优化范围之外
{
  "sideEffects": ["./path/to/module.js", "*.css"]
}
Last updated on
同时多次调用同个接口，如何只触发一次而不是触发多次如何实现上拉加载, 下拉刷新?