package.json 配置

coderhyh 7/18/2022 资料

# package.json字段

# name

如果项目是需要发版为npm包的，则name字段是必须的。因为它涉及到npm包的命名。

如果项目是不需要发版成npm包的，则name字段是可选的，不一定要设置。

name命名规范
- name字符串长度，必须小于或等于214个字符。
- 同一作用域内的包，可以用.或_作为开始字符
- 不能使用大写字母命名
- 因为name字段，在下载npm包时，会应用于url中，所以不能带任何不安全的URL字符。
不安全的URL字符
- 空格" "
- 大于小于号<>
- 方括号[]
- 花括号{}
- 竖线|
- 反斜杠\
- 插入号^
- 百分比%

私源npm包怎么命名？

格式：@[scope]/[name]。

举个例子：

笔者想要发布个私源是@coderhyh，包名是ping-url的包，则name需要命名为：@coderhyh/ping-url。

安装命令：npm install @coderhyh/ping-url。

# version --- 定义版本号

version字段用于定义版本号。

如果项目是为发布npm包，则必须包含此字段。如果是普通的项目，则此字段是可选的。

每次发布的version，必须是唯一的，之前发布的时候没使用过的。 version 的命名规则和注意点，可以参考package.json怎么管理依赖包版本？ (opens new window)

# description --- 描述

description用于描述当前项目的概况。发布的npm包，在搜索结果中，可以直接显示description内容，方便使用方直接了解包的功能。

# keywords --- 关键词

图中标签在package.json中对应的定义：

"keywords": [
  "ping url",
  "ping host",
  "ping"
]

1
2
3
4
5

keywords是标签，用于标记当前项目的重点词汇。同时，可以作为搜索关键词，提供给资源平台使用，进行索引。

# homepage --- 项目的官网

项目的官网主页地址

"homepage": ""

项目有对应官网地址的话，可以在homepage中声明。如果没有的话，也可以放个github项目源码入口

# repository --- 源码地址

项目的源码地址

"repository": {
  "type": "git",
  "url": ""
}

1
2
3
4

开源项目，这个字段很重要因为有意向的协作者，可以通过字段信息，便捷地进入查看项目源码

# license --- 协议类型

项目的协议类型

这个项目涉及到知识产权方面的知识。所以开源项目的时候，要重点考虑到底要用哪个协议，而不是无脑用MIT。

具体的可选协议列表，可查看SPDX License List (opens new window)

# author --- 作者

"author": {
  "name": "coderhyh",
  "email": "772567615@qq.com",
  "url": "https://coderhyh.top"
}

1
2
3
4
5

# contributors --- 协作者

协作者信息

格式是一个对象数组。对象内容和author一致

"contributors": [{
  "name": "aa",
  "email": "11@qq.com"
},{
  "name": "bb",
  "email": "22@qq.com"
}]

1
2
3
4
5
6
7

# files

声明有哪些文件，是需要作为依赖项，保留下来。不然，执行npm publish进行发布时，这些文件是会自动屏蔽上传的。同理，也可以使用.npmignore文件进行配置。

"files": [
  "dist/*.js",
  "lib"
]

1
2
3
4

如果没有files字段声明，则这些文件，都不会保留，npm包将不能使用

# main

使用npm包时，需要进行require(..)的操作。这个操作，会查看main字段，找到程序的主入口。

# bin

工具性质的npm包，一定有bin字段，对外暴露脚本命令。

举个例子

"bin": {
  "npg-cli": "bin/cli"
}

1
2
3

使用方安装npm-test-cli包后，npg-cli命令会进行注册，可以在CMD中识别并运行。

# scripts

项目脚本命令

# private

private和发布npm包相关

当private: true时，npm会拒绝发布当前项目。这是防止意外发布个人仓库的一种保护方式

# publishConfig

用于定义发布npm时，设置相关信息。

"publishConfig": {
  "registry": "http://127.0.0.1",
  "access": "public",
  "tag": "leon-tag"
}

1
2
3
4
5

registry 发布的npm私源地址
access 发布有作用域的包（比如@leon/ping-url），必须要设置access。
tag 指定当前版本对应的标签

信息可以在 versions/Current Tags 查看

如果没有显式指定tag，默认tag是latest

# types

项目如果是用TypeScript写的，则需要types字段，对外暴露相关的类型定义。

# module

性质等同于main字段。module用于ES6规范的模块，只要支持ES6，会优先使用module入口。这样，代码也可以启用tree shaking机制。

# unpkg

CDN方式下，引入当前npm包的链接。

# sideEffects

sideEffects格式：boolean | string[]。

sideEffects: false用于告知打包工具（webpack），当前项目无副作用，可以使用tree shaking优化。

sideEffects的值，也可以是一个文件路径组成的数组。告知哪些文件无副作用，可以使用tree shaking优化。

"sideEffects": [
  "a.js",
  "b.js"
]

1
2
3
4

"import xxx;"语句，只引入未使用，如果声明了sideEffects，则会被tree shaking删除掉。

并且，由于tree shaking只在production模式生效，所以本地开发会一切正常，生产环境很难及时发现这个问题。

当然，样式文件使用"import xxx;"的方式引入，会进行保留。

# engines

项目运行环境的要求声明。

"engines": {
  "node": ">=0.10.3 <15"
}

1
2
3

告知node版本需要在0.10.3与15之间，才可以运行当前项目。在不符合条件的环境中运行项目时，控制台会有报错输出。

# os

操作系统的要求声明。

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

1
2
3
4

# cpu

CPU的要求声明。

"cpu": [
  "x64",
  "ia32"
]

1
2
3
4

# workspaces

monorepo类型的项目，需要用到workspaces。它可以告知其他工具，当前项目的工作区间在哪里。

{
  "name": "workspace-example",
  "workspaces": [
    "./packages/*"
  ]
}

1
2
3
4
5
6

# bugs

开源项目用于接收bug反馈。

{
  "url" : "http://127.0.0.1",
  "email" : "772567615@qq.com"
}

小黄杂货铺

Choose mode