package.json配置详解，让你一看就会（上）

无名小卒攻城狮
8,692 阅读11分钟

大家好，我是小cc, 我期待的第一篇的文章，终于开笔了。我知道对于文章标题，没有让你眼前一亮（毕竟是个理科生，大家见谅哈），其实我之前看过很多类似的文章，每篇文章都有亮点，但难免有重合的地方，以及没有涉及到的地方，接下来，我会进行总结，让你秒懂package.json的配置。

u=3325534525,3843677322&fm=26&fmt=auto.webp

不不不，你必须信！！！ 废话不多说，让我们一起进入正题吧



name字段

命名规则：

  • 包名长度应大于零

  • 包名中的所有字符都必须是小写，即不允许大写或大小写混合的名称

  • 包名可以由连字符组成

  • 包名不得包含任何非 url 安全字符（因为名称最终成为 URL 的一部分）

  • 包名不应以.或开头_

  • 包的名称应该不包含任何前导或尾随空格

  • 包的名称应该不包含任何下列字符：~)('!*

  • 包名称不能与 node.js中核心模块相同，也不能与保留/列入黑名单的名称相同。

  • 包名长度不能超过214

  • 不能与其他模块名重复

如果大家想校验一个字符串是否是一个有效的npm包名，可以使用 这个validate-npm-package-name包，对大家开发脚手架比较有帮助

我们可以执行以下命令查看模块名是否已经被使用： npm view <packageName>



description 字段

是一个字符串，用于编写描述信息。有助于人们在npm库中搜索的时候发现你的模块。

比如大家在www.npmjs.com/ 上搜索项目的时候，下面红笔画的就是npm包的描述。

image.png

version字段

npm包版本。npm 包中的模块版本都需要遵循 semver. 规范，该规范的标准版本号采用 X.Y.Z 的格式。

其中，alpha：是内部测试版,一般不向外部发布,会有很多Bug.一般只有测试人员使用。beta：也是测试版，这个阶段的版本会一直加入新的功能。在alpha版之后推出。rc(Release Candidate)：最终测试版本；可能成为最终产品的候选版本，如果未出现问题则可发布成为正式版本。

比如：1.2.0-beta.1，1.0.1-alpha.1，3.0.0-rc.1

keywords字段

关键字，把关键词放进去。这是一个字符串数组。这有助于人们在npm搜索中发现您的包。

比如大家在www.npmjs.com/ 上搜索项目的时候，下面红笔画的就是npm包的关键字。

image.png


homepage字段

项目的主页地址。一般存放的是官网地址。

image.png

bugs字段
bugs用于项目问题的反馈issue地址或者一个邮箱。\

JavaScript复制代码

"bugs": { 
  "url" : "https://github.com/owner/project/issues",
  "email" : "project@hostname.com"
}


license字段

对npm包指定一个license来让用户知道他们的使用权利和和任何限制。字段的值通常是许可证的标识符代码——例如 MIT 或 ISC 之类的字符串，它们代表MIT 许可证和 ISC 许可证。如果你不想提供许可证，或者明确不想授予使用私有或未发布的软件包的权限，则可以将 UNLICENSED 作为许可证

您可以查看SPDX 许可证 ID 的完整列表。理想情况下，您应该选择 OSI批准的一种

如何选择一个许可证，推荐可以看一下这篇文章

www.ruanyifeng.com/blog/2011/0…

"license": "MIT"


author，contributors字段

author是具体一个人，contributors表示一群人，他们都表示当前项目的共享者。同时每个人都是一个对象。具有name字段和可选的url及email字段。

"author": {
  "name" : "yindong",
  "email" : "yindong@xx.com",
  "url" : "https://zhiqianduan.com/"
}

也可以写成一个字符串

author": "yindong yindong@xx.com (https://zhiqianduan.com/)"

但是在package.json中，通常只写一个author字段，那npm官网和github上的源码贡献者(contributors)是怎么来的呢？？？

在npm上，通过 npm owner add <user> <your-package-name> 即可添加成功。

****

在github上， contributors 现在有自己的规则，可以查看官网。



files字段

files属性的值是一个数组，内容是模块下文件名或者文件夹名，如果是文件夹名，则文件夹下所有的文件也会被包含进来（除非文件被另一些配置排除了））

可以在模块根目录下创建一个 .npmignore 文件，写在这个文件里边的文件，即便被写在files属性里边也会被排除在外。npmignore文件的工作原理与.gitnore文件类似。如果存在.gitignore文件，并且缺少.npmignore，则将使用.gitignore的内容。

无论设置如何，始终包含某些文件：

  • package.json

  • README

  • LICENSE / LICENCE

  • The file in the "main" field

比如在element-ui源码中，files字段包含如下：

  "files": [
    "lib",
    "src",
    "packages",
    "types"
  ],

当我们npm install 后查看node_modules时，看到的文件如下：至于change log如何生成，可以查看一下这篇文章。



fundig字段(赞助商)

您可以指定一个对象，该对象包含一个URL，该URL提供有关帮助开发软件包的方法的最新信息，或一个字符串URL，或以下内容的数组：

{
  "funding": {
    "type" : "individual",
    "url" : "http://example.com/donate"
  },

  "funding": "http://example.com/donate",

  "funding": [
    {
      "type" : "individual",
      "url" : "http://example.com/donate"
    },
    "http://example.com/donateAlso",
    {
      "type" : "patreon",
      "url" : "https://www.patreon.com/my-account"
    }
  ]
}

可以通过 npm fund 进行查看

main字段, module字段，browser字段

  • main : 定义了 npm 包的入口文件，browser 环境和 node 环境均可使用

  • module : 定义 npm 包的 ESM 规范的入口文件，browser 环境和 node 环境均可使用

  • browser : 定义 npm 包在 browser 环境下的入口文件



unpkg字段和jsDelivr字段

这两个字段都是做cdn优化服务的

unpkg

unpkg适用于npm上的所有内容。使用它可以使用以下URL快速轻松地从任何包加载任何文件。如果我们的npm包通过unpkg.com 被访问到，有两种方式。

第一种： 在根目录下创建umd 文件，里面存放需要访问到的文件路径，格式如下：

unpkg.com/:package@:version/:file
// 比如：
unpkg.com/react@16.7.0/umd/react.production.min.js
unpkg.com/react-dom@16.7.0/umd/react-dom.production.min.js

第二种： 在package.json 添加unpkg字段，里面存放需要访问到的文件路径，如果没有，访问的是main字段

// 比如：
unpkg.com/jquery
unpkg.com/foreign-cl

****注意：文件需要是umd格式。

jsDelivr

可以访问npm，github, wordpress上面所有的包

一、访问github的用法

https://cdn.jsdelivr.net/gh/用户名称/仓库名称@版本号/目录

二、访问npm的用法

https://cdn.jsdelivr.net/npm/包名@版本号/目录


bin字段

bin项用来指定每个内部命令对应的可执行文件的位置。如果你编写的是一个node工具的时候一定会用到bin字段（实际上npm本身也是通过bin属性安装为一个可执行命令的）。

当我们编写一个cli工具的时候，需要指定工具的运行命令，比如常用的webpack模块，他的运行命令就是webpack。在源代码中，package.json文件配置如下：

"bin": {
  "webpack": "bin/index.js",
}

模块安装的时候，若是全局安装，则npm会为bin中配置的文件在bin目录下创建一个软连接（对于windows系统，默认会在C:\Users\username\AppData\Roaming\npm目录下），若是局部安装，则会在项目内的./node_modules/.bin/目录下创建一个软链接。

man字段

制定一个或通过数组制定一些文件来让linux下的man命令查找文档地址

directories字段

CommonJs通过directories来制定一些方法来描述模块的结构，看看npm的package.json文件registry.npmjs.org/npm/latest ，可以发现里边有这个字段的内容。

directories.lib

告诉用户模块中lib目录在哪。如果你在这里指定了bin目录，这个配置下面的文件会被加入到bin路径下，如果你已经在package.json中配置了bin目录，那么这里的配置将不起任何作用。

directories.man

指定一个目录，目录里边都是man文件，这是一种配置man文件的语法糖。

directories.doc

在这个目录里边放一些markdown文件。

directories.example

放一些示例脚本。

repository字段

指定一个代码存放地址，对想要为你的项目贡献代码的人有帮助。url最好是一个公开的地址

{
  "repository": {
    "type": "git",
    "url": "https://github.com/npm/cli.git"
  }
}

如果包的package.json不在根目录中（例如，如果它是monorepo的一部分），则可以指定它所在的目录：

{
  "repository": {
    "type": "git",
    "url": "https://github.com/facebook/react.git",
    "directory": "packages/react-dom"
  }
}


scripts字段

scripts属性是一个对象，里边指定了项目的生命周期个各个环节需要执行的命令。key是生命周期中的事件，value是要执行的命令。详见docs.npmjs.com/misc/script…

config字段

config字段用于添加命令行的环境变量。

{
  "name" : "writepress",
  "config" : { "port" : "8080" },
  "scripts" : { "start" : "node server.js" }
}

然后，在server.js脚本就可以引用config字段的值。

console.log(process.env.npm_package_config_port); // 8080


dependencies字段

dependencies字段指定了项目运行所依赖的模块。

通过命令 npm i xxx -S 或者 npm i xxx --save 来安装一个包。npm 5.x 开始可以省略 --save，即如果执行 npm install xxx，npm 一样会把包的依赖添加到 package.json 中去。要关闭这个功能，可以使用 npm config set save false。

如果直接只写一个包的名字，则安装当前 npm registry 中这个包的最新版本

在实际开发中，生产依赖可以分为几类：工具包，组件库，前端框架等。

使用url 作为开发依赖：

您可以指定tarball URL来代替版本范围。(用npm pack生成一个tarball URL)

 npm install https://normal-test-use.oss-cn-beijing.aliyuncs.com/0.0.1/foreign-cl-0.0.1.tgz

使用git url 作为开发依赖：

<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

必须是 git, git+ssh, git+http, git+https, or git+file其中之一。

使用GitHub URLs作为开发依赖：

{
  "dependencies": {
    "express": "expressjs/express",
  }
}

使用本地路径作为开发依赖：

{
  "dependencies": {
    "react": "../react"
  }
}

版本：

有关指定版本范围的详细信息，请参见semver。

下面列出几种常见的：

  • ~ version 会匹配最近的小版本依赖包，比如~1.2.3会匹配所有1.2.x版本，但是不包括1.3.0
  • ^version 会匹配最新的大版本依赖包，比如^1.2.3会匹配所有1.x.x的包，包括1.3.0，但是不包括2.0.0
  • *version 这意味着安装最新版本的依赖包
  • version 版本必须与版本完全匹配
  • < version 小于版本
  • <= version 小于等于版本


devDependencies字段

开发环境的依赖

使用 npm i -D 或者 npm i --save-dev

在实际开发中，大概有这么几类可以归为开发依赖：构建工具， 预处理器，测试工具，babel, eslint, typescript.

有关指定版本范围的详细信息，同上。



peerDependencies字段

对等依赖： 描述的是一种表达插件与其宿主包之间的“依赖关系”。某种说法，“我只在插入我的主机包的 1.2.x 版时才能工作，所以如果你安装我，请确保它与兼容主机一起使用。

比如在element-plus中，要求项目的vue版本在3.1.x版本以上，如果我们安装vue2.x的版本，就不会安装成功。

 "peerDependencies": {
    "vue": "3.1.x"
  },


peerDependenciesMeta字段

当用户安装您的包时，如果尚未安装peerDependencies中指定的包，npm将发出警告。peerDependenciesMeta字段用于向npm提供有关如何使用对等依赖项的更多信息。具体来说，它允许将对等依赖项标记为可选。

比如，在vite中，peerDependencies和peerDependenciesMeta如下，sass，stylus和less被标记为可选。

  "peerDependencies": {
    "less": "*",
    "sass": "*",
    "stylus": "*"
  },
  "peerDependenciesMeta": {
    "sass": {
      "optional": true
    },
    "stylus": {
      "optional": true
    },
    "less": {
      "optional": true
    }
  },

如果项目中没有安装sass，stylus或less时，会报出如下警告：



bundledDependencies字段

捆绑依赖，在npm pack 打包成tgz时将会捆绑依赖一同打包。

比如，foreign-cl的package.json文件如下：

{
  "name": "foreign-cl",
  "version": "0.0.1",
  "main": "index.js",
  "bundledDependencies": [
    "jquery"
  ],
  "dependencies": {
    "jquery": "^3.6.0",
    "moment": "^2.29.1"
  }
}

当我们执行npm pack 时，会生成foreign-cl-0.0.1.tgz包

这个tgz包中的node_modules里面只有jquery。

private字段

如果这个属性被设置为true，npm将拒绝发布它，这是为了防止一个私有模块被无意间发布出去。

"private": true

optionalDependencies字段

对于一个依赖包，如果在镜像仓库中找不到就会导致安装失败。

{
  "name": "my-vue-app",
  "version": "0.0.0",
  "dependencies": {
    "vue": "^3.2.16",
    "test111": "^1.2.0"
  }
}

如果希望npm继续安装， 可以将其放入optionalDependencies对象。

{
  "name": "my-vue-app",
  "version": "0.0.0",
  "optionalDependencies": {
    "test111": "^1.2.0"
  },
  "dependencies": {
    "vue": "^3.2.16"
  }
}



publishConfig字段

在npm包发布时使用的配置，是一个对象，我们可以在里面设置tag(标记)，registry（仓库地址），access（访问权限）

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


os字段

可以指定你的模块只能在哪个操作系统上运行

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

比如在foreign-cl中package.json如下：

{
  "name": "foreign-cl",
  "version": "1.0.1",
  "os" : ["linux"]
}

当我们在window下载时，报错如下：



cpu字段

限制模块只能在某种架构的cpu下运行，同OS字段。

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


engines字段

指定项目工作的环境。除非用户设置engine-strict标记，这个字段只是建议值。当用户版本不符合指定值时也不影响依赖的安装。

{ "engines" : { "node" : ">=0.10.3 <0.12", "npm" : "~1.0.20" } }




看到这里你以为完了嘛？？

image.png

还有一个workspace字段，以及一些字段(比如broswer，main, modules等)的细节问题，我们下篇文章在来说一说。

如果您发现有任何问题的话，欢迎随时指正，作者看到后一定第一时间回复。

如果这篇文章对你有帮助的话，麻烦手动点一下赞哦，激励一下作者。



站在巨人的肩膀上

unpkg.com/ www.jsdelivr.com/ docs.npmjs.com/cli/v6/conf… www.cnblogs.com/tzyy/p/5193…
juejin.cn/post/698717… zhuanlan.zhihu.com/p/56002037 www.cnblogs.com/murenziwei/… www.yht7.com/news/163530

avatar
文章
阅读
粉丝