做前端这几年,我前前后后往 npm 上发过几十个包,从最开始被各种 403、409 报错折腾到怀疑人生,到后来闭着眼睛十分钟发一个,中间踩过的坑凑一凑都能写本小册子了。这篇“npm 包发布全流程指南”不跟你整那些虚的,就是把一条从零到一、亲测能跑通的发布链路完整捋一遍,顺带把那些高频出现的报错、环境问题、镜像源问题、权限问题一次讲清楚。不管你是在公司内网做私有包,还是想发一个开源工具给全世界的开发者用,这篇都能用得上。
如果你正准备发布自己的第一个 npm 包,或者你曾经发布失败过、卡在某一步不知道怎么处理,那这篇文章正好是给你写的。我尽量把每一步的操作细节、背后原因、常见坑位都讲透,保证你在自己的电脑上照着敲就能走完整个流程。
1. 发布前的环境准备,先把“出师未捷”的问题解决
很多人在发布 npm 包之前,连 npm 命令都跑不起来。这听起来有点荒诞,但实际情况就是这么普遍。你去网上搜“npm 不是内部或外部命令”“npm 无法加载文件 npm.ps1”,能搜出一大片求助帖,这俩问题我在帮同事排查的时候遇到过无数次,基本属于新手入门的第一道坎。
1.1 环境变量与 npm 命令识别问题
“npm 不是内部或外部命令,也不是可运行的程序或批处理文件”这个报错,几乎都是因为 Node.js 安装之后,它的安装目录没有加到系统的 PATH 环境变量里。Node.js 安装包在正常的图形化安装流程中会自动配置这步,但如果你是用绿色解压版、或者安装时手动改了目录、又或者电脑上之前装过别的版本没清理干净,就很容易出现这种问题。
解决办法也比较粗暴直接:找到你 Node.js 实际安装的位置,确认里面有 npm.cmd 和 node.exe 这两个文件,然后把这一层目录完整复制出来,加到系统环境变量的 Path 里。具体操作是:右键“此电脑”->“属性”->“高级系统设置”->“环境变量”,在系统变量里找到 Path,新建一条,把 Node.js 目录粘贴进去,然后保存。改完之后记得把命令行窗口全部关掉重开,再执行 node -v 和 npm -v 验证一下。
我遇到过最隐蔽的一种情况是:环境变量配了,但是配置的是用户变量,而命令行工具是以管理员身份打开的,导致读不到。这种事儿排查起来非常费时间,所以我一般建议直接配在系统变量里,一劳永逸。
1.2 Windows 下 PowerShell 执行策略导致 npm 无法运行
“npm : 无法加载文件 C:\Program Files\nodejs\npm.ps1,因为在此系统上禁止运行脚本”,这个报错是 Windows 用户的高频问题。原因是 PowerShell 默认的执行策略是 Restricted,限制运行本地脚本文件,而 npm 的全局命令在 PowerShell 下是通过 npm.ps1 这个脚本去调用的,所以直接被拦了。
解决方案不是去删文件,而是调整 PowerShell 的执行策略。用管理员身份打开 PowerShell,执行:
powershell复制Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
然后输入 Y 确认。这样既允许运行本地的 .ps1 脚本,又能保持对从网络下载的脚本的签名校验,算是一个安全与便利之间的折中方案。改完之后重开终端,npm 就能正常跑了。
值得提醒的是:很多人搜到这个方案之后,在普通的 PowerShell 窗口执行,发现报错“因为未以管理员身份运行”,然后就开始怀疑是策略设错了。其实不是,是权限不够,必须以管理员身份运行 PowerShell 再执行这条命令才有效。
1.3 换源与镜像源配置
npm 官方源的服务器在国外,国内网络环境下安装依赖经常慢到令人窒息,所以“换源”基本是国内开发者的必操作。最常见的做法是使用淘宝镜像源 npmmirror,一条命令配完:
bash复制npm config set registry https://registry.npmmirror.com/
配置完之后可以执行 npm config get registry 查看当前源,确认是否生效。还有一些人用 cnpm 或者 pnpm 来装依赖,这里简单说下区别:cnpm 是淘宝团队做的客户端,专门走淘宝源,安装速度快,但有时候会产生一些奇奇怪怪的兼容问题(比如某些依赖的软链结构不一样);pnpm 则是一个全新的包管理器,通过硬链接和软链接的方式节省磁盘空间、提升安装速度,而且对 monorepo 支持很好。至于“npm 和 pnpm 到底哪个好”,这事情没有标准答案,但目前趋势上 pnpm 在工程化项目里的占比在明显上升。
不过
