我第一次发布npm包的下午就在这一行npm publish上卡了整整三个小时。报错信息长得一模一样全是一串红色403我当时几乎以为自己连账号密码都能敲错。后来才发现真正的原因比我想象中蠢得多登录的registry不是官方源登录状态根本没进对地方。这套流程兜兜转转踩完一遍之后我决定把从账号准备、package.json字段、正常发布流程、版本管理到常见错误排查的完整心得整理出来给第一次发包、或者已经发过几次但总在某些报错前犯迷糊的同学一份能直接照着抄的清单。1. 发布前的硬性准备账号、邮箱、registry、登录状态很多人一想到“发布npm包”第一反应就是打开编辑器写代码。但现实中我在帮同事排查发不出去的问题时十个里有八个是卡在发布前的准备工作上。这些准备工作看起来不起眼却能在后面省下几个小时。1.1 先确认账号和邮箱验证注册npm官网账号这件事不用多解释但有一个细节特别容易被忽略邮箱验证。npm官方规定发布包之前账号对应的邮箱必须完成验证。如果你注册完账号后没去邮箱里点验证链接npm publish会直接返回一条403消息里写着类似You must verify your email before publishing。我第一次看到这条报错时还以为是什么权限问题实际上邮件点一下就好。另外现在npm账号普遍支持两步验证2FA。我的建议是开发账号最好开启毕竟发布包相当于对外推送代码被劫持账号发布恶意版本的事以前不是没发生过。你可以在官网的设置里绑定登录和发布时按提示输入动态码就行。1.2 先检查你的registry到底指向哪里这是整个准备阶段最阴间的一个坑也是我那次卡三个小时的元凶。npm默认的官方源地址是https://registry.npmjs.org/很多同学为了下载依赖快一些会全局把registry切换成某个公共镜像源。下载走镜像确实快但问题在于镜像源通常只允许读取不允许上传。你对着镜像源执行npm login它可能根本走不通你直接npm publishnpm会把你送向一个陌生的登录认证体系或者干脆拒绝你的上传请求。所以在发布前先跑一句npm config get registry如果输出的不是官方源地址建议在项目根目录创建一个.npmrc文件把项目级配置覆盖为官方源registryhttps://registry.npmjs.org/项目级.npmrc的优先级高于用户级配置只影响当前这个项目不会把你整个下载环境都拖回慢速状态。这是我目前见过最稳妥的做法日常下载依赖走镜像需要发布的单项目固定走官方源。1.3 登录状态怎么看、存在哪里执行npm login之后登录凭证会写入用户目录下的~/.npmrc文件。这一步对很多人来说是个黑盒出问题也无从查起。发布前建议先用这条命令确认当前身份npm whoami如果打印出你的用户名说明登录状态正常如果输出undefined、null或一行错误说明登录没成功。还有一种情况登录时设置了两步验证但发布时收不到动态码这通常是网络原因导致短信或令牌服务请求超时换个网络环境重新登录就好。记住一个原则登录和发布必须走同一个registry。登录时用了官方源发布时又因为某种原因切到了镜像源照样会报401或403。2. package.json里那些决定“能不能发、发了什么”的字段很多人写package.json是IDE自动生成的填个name、version就完事。发布时间一长你就会发现真正卡住你的不是代码而是这几个字段。2.1 name和version就是“法律条文”npm的包名全局唯一就像域名一样。你发布一个包如果名字已经被人占用了registry不会让你覆盖别人的包直接403。所以取名前先查一下npm view 你想起的包名如果返回404说明这个名字当前没人用可以注册如果返回了一堆包信息说明名字被占了需要换个名字或者加上scope前缀你的作用域/包名。version字段也有讲究同一个版本号不能重复发布。比如你发布过1.0.0后来把代码改了但忘记改version再执行npm publishregistry会拒绝提示You cannot publish over the previously published versions。很多人第一次看到这个报错以为是权限问题其实就是版本号撞了。npm的版本号是严格的语义化版本格式主版本.次版本.修订号不能是1.0或v1.0.0这种写法。2.2 想清楚包里到底装什么files白名单与.npmignore黑名单发布包不等于把整个项目原封不动传上去。你在本地开发需要的src目录、测试用例、配置文件用户根本用不到反过来漏了构建好的dist产物用户安装后跑不起来。npm通过files字段做白名单控制{ files: [dist, README.md] }白名单机制是列出来的目录和文件一定会被打包其他杂七杂八的东西默认不进去。这样最干净我强烈推荐优先用files而不是.npmignore。如果你选择了.npmignore黑名单方式注意一个隐藏规则一旦存在.npmignorenpm就不会再读取.gitignore。所以有些项目的.gitignore写了一大堆结果发布时却把node_modules、临时文件都打进了包里多半就是因为新增了.npmignore但没同步。另外还有一个总会包含项package.json、README.md、LICENSE这些文件无论怎么配置都会被打进去不用额外加。2.3 入口字段决定用户怎么用你的包main字段指向CommonJS入口module字段指向ESM入口types指向TypeScript类型声明exports则是Node.js新版本主推的精细化导出控制。发布前自检一下这几个字段引用的文件是否存在于发布包里否则用户require或import你的包时会直接报Cannot find module。很多项目用TypeScript构建后产物在dist目录main填的是dist/index.js。如果你忘了在files里加上dist登录、发布、版本号全都没问题包也发布成功了但用户装下来就是模块缺失。这种“发布成功但根本不能用”的包比发布失败更坑。2.4 private字段会拦截整个发布package.json 里如果写着private: truenpm 会拒绝发布报错提示里会出现This package has been marked as private。这是很多脚手架生成项目后默认带上的字段。我见过有人从GitHub模板拉了个项目改都没改就发布卡在这一步半天。另外license字段如果写成UNLICENSED在某些情况下也会被registry提示问题。建议明确写成标准的SPDX表达式比如MIT、Apache-2.0。3. 从零跑通一次完整发布pack、dry-run、publish、验证准备工作和字段确认完下面就是实打实的发布操作。很多教程直接一句npm publish完事但实际发布中我建议至少完成四个步骤。3.1 发布前先自检npm pack和--dry-run发布前先执行npm pack会在本地生成一个.tgz压缩包。这个包的内容等价于你将发布到registry上的包内容。看看里面有没有你不想发出去的文件比如node_modules、密钥文件、本地图片资源。npm pack生成了压缩包后还能进一步用tar -tzf 包名.tgz查看包内的文件全列表。另一个更简单的方式是直接在发布前模拟一次npm publish --dry-run这条命令会在本地完整执行发布前的所有流程包括跑before脚本、打包、列出最终发布文件列表但不会真正上传。你可以把它理解为“预演发布”。我自己习惯的组合是改完代码后先npm pack看一眼包体大小和文件列表确认没问题再npm publish。别看这多花一分钟能拦下七八成的低级事故。3.2 正式发布的第一发假设你是第一次发布新包在项目根目录依次执行npm login npm publish如果你发布的是scope包比如你的作用域/包名那么公开发布需要显式加参数npm publish --access public如果不加npm默认认为scope包是私有的而私有发布需要收费组织账号所以会直接拒绝。发布过程中npm会执行prepublishOnly脚本。这个脚本名很容易和老的prepublish混淆我特别提醒一下能用prepublishOnly就别用prepublish。因为老逻辑里prepublish在npm install时也可能被触发容易产生诡异行为。推荐在发布前自动构建和测试{ scripts: { build: tsc, test: jest, prepublishOnly: npm run build npm test } }这样每次npm publish时会先构建再测试全部通过才真正打包上传避免手忙脚乱忘了构建就发布。3.3 发布完成后必须验证的三件事发布命令执行完显示 包名版本号并不代表万事大吉。我每次发布后都会顺手做三个验证第一用npm view 包名查看registry上的信息确认版本号、描述、关键词都已经更新。第二在另一个空目录里执行npm install 包名然后写一行代码真正引用一下确认能跑通。第三到npm官网的个人包列表页面看一眼确认包名没有拼错、描述没有乱码。这三个验证加起来不到三分钟但能发现很多“命令执行成功但实际不能用”的隐患。4. 版本更新不只是改数字semver、npm version、dist-tag发布过一次之后后续的工作就是持续迭代。版本号怎么改、预发布版本怎么发这里面有一套自己的玩法处理不好很容易让用户下错版本。4.1 semver的规则比你想的简单语义化版本号主版本.次版本.修订号规则就三条修复bug且不改变API递增修订号新增功能且向后兼容递增次版本号有破坏性API变更递增主版本号。举个例子1.2.3修复bug后变成1.2.4加了新功能变成1.3.0改了不兼容的接口变成2.0.0。这套规则看起来简单但实际发布中很多人偷懒每次发布都手动改一下版本号经常改错位数。比如明明只是修了个bug却把次版本号递增了虽然也能发布但会让使用者产生“这个更新功能不小”的误判。4.2npm version命令比手改版本号可靠在git仓库中我更推荐用npm version系列命令来管理版本npm version patch # 1.2.3 - 1.2.4 npm version minor # 1.2.3 - 1.3.0 npm version major # 1.2.3 - 2.0.0这条命令不仅会修改 package.json 的版本号还会自动生成一个对应的git tag。如果你需要推送代码和tag再执行git push git push --tags如果项目不是git仓库npm version可能会报 git 相关错误。那就只能手动改 package.json 里的版本号这个需要注意。4.3 预发布版本千万别污染latest标签npm 的 dist-tag 机制是我觉得很多教程都一笔带过、但实际超容易踩坑的部分。默认情况下npm publish会把新版本自动标记为latest。也就是说用户执行npm install 某个包时装到的就是latest标签指向的版本。问题出在预发布版本上。假设你当前正式版是1.0.0用npm version prerelease --preidbeta生成了1.0.1-beta.0然后直接npm publish发布。如果不加任何额外参数这个预发布版本可能直接被标记为latest用户执行普通安装时就会装到beta版本这可是发布事故级别的坑。正确的做法是给预发布版本单独指定一个标签npm publish --tag beta这样一来latest仍然指向1.0.0beta版本只有主动执行npm install 包名beta才会被安装。用下面这几条命令可以随时查看和管理标签npm dist-tag ls 包名 npm dist-tag add 包名1.0.0 latest5. 常见错误全拆解看到报错不要慌按链路反推根因发布过程中让人最崩溃的是那种“报错信息长得差不多但原因根本不同”的情况。我把这几年在发布场景里遇到的错误按状态码和关键词做了个分类每类背后都对应完全不同的处理思路。5.1 403是老三样但三种403完全不是一回事403是我见过最会伪装错误的状态码。同样是403底下细节文字不一样处理方式天差地别。我整理了一个对照表放在下面报错特征文字真实原因正确操作you do not have permission to publish包名已被他人注册或你对某个包没有写权限改名或用scope前缀区分You cannot publish over the previously published versions当前版本号已发布过撞版本了升版本号或npm version patchYou must verify your email before publishing账号邮箱未验证去邮箱点击验证链接you must set --access publicscope包试图默认私有发布加--access public第一次遇到403时别再盯着“Forbidden”三个字猜了把下面那行小字读完基本就能定位问题。多数时候“权限不足”只是表象真正的限制来自包名和版本号。5.2 401、400也是发布高频401代表身份认证失败最常见的情况就是登录状态失效。token过期、.npmrc里的凭证被清理、或者登录时用的registry和发布时的registry不一致都可能出现401。解决方法是重新npm login并确保npm whoami能正常输出你的用户名。400通常是 package.json 本身有问题。例如 version 字段格式不合法、repository 字段结构错误、license 字段写入了SPDX无法识别的值。这类错误会在发布前被registry的元数据校验挡下来。遇到400先检查 package.json 里的字段格式尤其留意repository是不是长这样{ repository: { type: git, url: https://github.com/你的仓库地址.git } }5.3 网络与镜像源引发的发布疑难杂症我把网络类问题单独放一节因为这类问题的报错信息最具迷惑性。比如上传大包时连接中断、请求超时npm会报ECONNRESET、ETIMEDOUT之类。很多人以为是代码问题改来改去浪费时间。遇到网络类错误我一般按这个链路排查先确认当前项目的.npmrc是不是指向了官方源发布必须在官方源然后确认网络到registry.npmjs.org是否稳定通顺有些办公网络访问官方源很慢上传超大包超时是家常便饭最后清理缓存重试npm cache verify这里有个经验之谈下载依赖你可以长期使用镜像源但发布操作请老老实实切回官方源。不要试图把发布请求指向镜像源它们大概率只负责同步和读取上传接口验证体系不同发不上去不说报错还特别难懂。6. 发布之后的事unpublish、deprecate、scope包与团队协作很多人以为npm publish跑完就结束了其实发出去只是开始。后续的撤销、废弃、团队权限处理都有不少讲究。6.1 发错包了怎么办unpublish的72小时规则发布后如果立刻发现包里有严重问题可以执行npm unpublish 包名版本号但注意npm对unpublish限制很严格通常只有发布后72小时内的包才允许撤销且如果这个包已经有不少依赖它的用户即使时间没超可能也不让你删。所以正确姿势是发布后发现问题短时间内赶紧撤销重发超时之后就不要再想着删了。6.2 长期标记废弃请用deprecate如果某个老版本因为历史原因不想让用户继续使用但出于兼容考虑又必须保留使用deprecate才是正确姿势npm deprecate 包名版本号 该版本存在已知问题请升级到xx版本用户在安装这个版本时会看到你写的警告信息。这个操作没有时间限制什么时候都能执行也不会破坏依赖。我现在的团队已经形成了共识撤销是急救手段废弃是日常手段。6.3 scope包与团队发布的最后提醒scope包形如组织名/包名天然适合团队内部或者组织化发布。公开发布时记得每次都带--access public。如果你们团队在npm上开通了组织成员能否发布由组织权限控制发包前确认账号加入了对应组织否则会收到无权限类403。关于团队协作我还有一个建议发布npm包的账号不要用个人私人的邮箱否则离职交接时包的所有权处理会非常痛苦。尽量用团队公共账号或者在组织权限体系里让每个成员独立账号并单独授予发布权限这样每个人的发布记录可追溯权限回收也方便。最后再说一个我自己的小习惯发布脚本尽量封装成固定的命令比如在package.json里写一个release脚本内部依次完成构建、测试、版本号递增、发布并统一指定tag。这样不管谁执行发布流程都是一致的。npm包发布这条路本身不复杂复杂的是那些分散在账号、字段、标签、权限里的小细节。把细节捋顺了发布就是一条命令的事。