从0到1开发一个自己的npm包完整过程

从 package.json 出发

name

name 字段在 npm 注册表中唯一标识一个包。

如果你希望发布的包属于某个组织或团队，可以使用 scoped packages。Scoped packages 的名称以 @scope/ 开头，例如 @your-org/package-name。其中Scoped packages允许你创建一个命名空间，从而避免命名冲突。例如，如果你有一个名为 utils 的包，可以将其命名为 @your-org/utils，这样即使其他开发者也有一个名为 utils 的包，也不会产生冲突。

version

version字段表示该项目包的版本号。

• 主版本号：当新版本无法兼容基于前一版本的代码时，则提高主版本号；
• 次版本号：当新版本新增了功能和特性，但仍兼容前一版本的代码时，则提高次版本号；
• 修订号：当新版本仅仅修正了漏洞或者增强了效率，仍然兼容前一版本代码，则提高修订号；

^ 兼容某个大版本

^意味着下载的包可能会是更高的次版本号或者修订版本号。(也就是主版本不能变，次版本、修订版本可以随意变)。

兼容某个大版本

如：^1.1.2 ，表示>=1.1.2 <2.0.0，可以是1.1.2，1.1.3，.....，1.1.n，1.2.n，.....，1.n.n 

~ 兼容某个次版本

~意味着有可能会有更高的修订版本号。(也就是主版本、次版本不能变，修订版本可以随意变)。

兼容某个次版本 

如：~1.1.2，表示>=1.1.2 <1.2.0，可以是1.1.2，1.1.3，1.1.4，.....，1.1.n 

private

private 字段用于指示该包是否为私有包。如果将 private 字段设置为 true，则该包不会被发布到 npm 公共注册表。这对于确保某些包仅用于内部开发或特定项目非常有用。

publishConfig

publishConfig 字段在 package.json 文件中用于指定发布包时的一些配置选项。这个字段可以帮助你自定义发布行为，例如指定发布到哪个注册表、设置访问权限等。

例如（这样就会发布到指定服务器上（私服））：

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

注意：即使设置了private为false，且设置了publishConfig的registry为私服地址。发包后，仍会发布到私服，而不会发布到npm上。

typings

typings字段用来指定TypeScript的入口文件。

files

files配置是一个数组，用来描述当把npm包作为依赖包安装时需要发布的文件列表。

当npm包发布时，files指定的文件会被推送到npm服务器中，如果指定的是文件夹，那么该文件夹下面所有的文件都会被提交。比如可以在该文件中这样写：

// package.json
 "files": [
    "lib",
    "es"
  ],

如果有不想提交的文件，可以在项目根目录中新建一个.npmignore文件，并在其中说明不需要提交的文件，防止垃圾文件推送到npm上。这个文件的形式和.gitignore类似。写在这个文件中的文件即便被写在files属性里也会被排除在外。比如可以在该文件中这样写：

// .npmignore
node_modules

.vscode

build

.DS_Store 

main、module

exports

sideEffects

发布一个npm包

通常来讲，一个好的npm包中的package.json中的配置项，在上面已经大都提到了。

接下来主要介绍一下发包的流程，以及一些注意事项。

初始化项目

跟我们平时初始化前端项目一样，直接输入 npm init 初始化项目。注意要发布到 npm 公共仓库里 private 属性要设置为 false，还确保 package.json 中的 name 字段是唯一的，否则发布时会失败，可以自己在 npm 网站上搜索包名或者通过如下命令查看是否已经存在同名包：

npm view <packageName>

例如，我们所有react包：

➜  ~ npm view react

react@18.3.1 | MIT | deps: 1 | versions: 2045
React is a JavaScript library for building user interfaces.
https://reactjs.org/

dist
.tarball: http://localhost:4873/react/-/react-18.3.1.tgz
.shasum: 49ab892009c53933625bd16b2533fc754cab2891
.integrity: sha512-wS+hAgJShR0KhEvPJArfuPVN1+Hz1t0Y6n5jLrGQbkb4urgPE/0Rve+1kMB1v/oWgHgm4WIcV+i7F2pTVj+2iQ==
.unpackedSize: 318.1 kB

dependencies:
loose-envify: ^1.1.0 

dist-tags:
beta: 19.0.0-beta-26f2496093-20240514
canary: 19.0.0-rc-5c56b873-20241107
experimental: 0.0.0-experimental-5c56b873-20241107
latest: 18.3.1
next: 19.0.0-rc-5c56b873-20241107
rc: 19.0.0-rc-5c56b873-20241107

published 6 months ago by react-bot <react-core@meta.com>

执行npm init 初始化项目

npm init

注意：配置文件中的版本号 version 里面的值，每次发布的时候只能在前一次的基础上往上增加，否则发布的时候会失败。

打包脚本

比如：

"compile:rollup": "rollup -c --bundleConfigAsCjs",
"push": "yarn compile:rollup && yarn publish"

注意事项：

• 合理配置dependencies和devDependencies，因为发包后，dependencies会被跟随包一起构建。如果配置不合理，无意会增大包体积。
• 如果包发布到私服，使用方需要配置.npmrc文件，配置私服地址，从私服拉取npm包。
• 配置sideEffects，不会你的包不支持treeShaking吧。
• 合理配置npm包的入口，通常入口文件很简单，只是简单的导出。

开发项目

很多人一想到封装这些就觉得是一件很难的事，其实除了前端中我们经常用到的 ui 组件库，还有很多东西都是可以自己来封装成 npm 包的，哪怕只是一个处理某些数据的 function 函数同样是可以发布成 npm 包的。当然，这里也不推荐大家往 npm 上随便发布一些无意义的包，但是对于我们很多项目中用到的一些自己的公共方法，就完成可以封装成一个自己的 npm 包以便在不同的项目中复用。

本地调试

将本地的 npm 包链接到全局，直接在本地 npm 包源码目录下输入命令：

npm link

这样就会在本地的全局 npm 目录中创建一个我们自己的包的符号链接，可以通过 npm list -g 命令来查看是否生效。然后再到需要使用我们的包的项目目录中，输入命令：

npm link <packageName>

这样项目中就通过上一步设置的全局软链接链接到了我们本地的 npm 开发目录，使用的时候就和项目中的 node_modules 目录下安装的依赖一样的效果。而且直接修改本地的 npm 包源码，项目中使用时也会实时生效，这样对我们本地调试就很方便。

清理

调试完成后后，我们需要清理掉本地的设置。清理掉全局的软链接，随便在哪终端命令输入：

npm unlink -g <package-name>

清理项目中使用的全局软链接，在项目的根目录输入：

npm unlink <package-name>

发布

通过 npm pack 发布项目

可以通过打包当前package为tgz文件，然后手动上传到自己的镜像库地址。

步骤如下：

执行打包命令：

npm pack

执行完后会在项目根目录下生成一个 [packagename].tgz 压缩文件，将刚刚打包的文件上传到对应目录即可。

通过npm publish 发布项目

在package.json中增加publishConfig配置，registry就是镜像库的地址。

登录仓库

执行npm login 登录当前的仓库地址。

注意：如果是在全局执行的npm login 要设置npm 的仓库地址为当前要上传包的地址，如果在项目根目录下执行，可以配置npmrc文件的registry值为要上传的仓库地址。

如：我们想发布npm包到npm官网，但我们通常会设置npm的仓库地址为镜像地址，此时执行npm login就会报错，必须将npm 的registry地址设置为npm源地址。

发布

在项目根目录下执行：

npm publish

就可以发布项目了，成功后也会有相应提示。