VSCode本身不校验package.json是否符合npm publish要求,必须依赖npm pack等CLI命令或JSON Schema类插件进行发布级验证;npm pack可检查name合法性、version语义化、main/exports路径存在性及files字段完整性,而插件无法替代npm publish --dry-run的最终registry校验。

VSCode 本身不校验 package.json 是否符合 npm publish 要求,必须靠 CLI 工具或插件补足检查能力;光靠语法高亮或悬停提示,根本发现不了字段缺失、私有源配置错误、main/exports 字段路径不存在等发布级问题。
npm pack 前必跑的本地验证命令
真正能模拟 npm publish 行为的只有 npm pack —— 它会按真实发布逻辑打包,并在控制台报出所有阻断性错误:
-
npm pack会检查name是否合法(不能含大写字母、空格、下划线开头)、version是否为有效语义化版本 - 它会验证
main、types、exports字段指向的文件是否存在,路径是否拼写正确(比如写成"main": "./dist/index.js"但实际生成在./lib/) - 若
files字段存在,npm pack会确认声明的路径是否真的被包含,避免漏发关键文件 - 执行后生成一个
.tgz文件,你可以用tar -tzf package-name-1.0.0.tgz解包确认内容结构
VSCode 插件能查什么、不能查什么
Version Lens 只管版本号更新,对发布准备毫无帮助;真正能辅助检查 package.json 发布合规性的,是以下两类插件:
-
JSON Schema 验证类:装好
redhat.vscode-yaml(支持 JSON Schema)后,在package.json顶部加注释// @schema https://json.schemastore.org/package.json,VSCode 就能实时标出repository.url缺协议、keywords非数组等结构错误 -
npm CLI 集成类:npm Helper 扩展提供右键菜单「Validate package.json」,本质是调用
npm view . --json,可提前暴露字段类型错(如把license写成对象而非字符串) - 注意:所有插件都无法替代
npm publish --dry-run(npm v9+ 支持),它才是真正走通 registry 认证、权限、私有域白名单的最终校验
容易被忽略的 workspace 和 private 字段陷阱
你在 VSCode 里打开的是多根工作区,或本地开发时用了 "private": true,这两个场景会让常规检查完全失效:
- 多根工作区中,VSCode 默认只激活第一个文件夹的
package.json语言服务;其他子包的exports或peerDependencies错误不会被提示 -
"private": true虽然阻止npm publish,但npm pack仍能成功——很多人误以为“打不出包=安全”,结果 CI 流水线里因未设该字段直接发到公开 registry - 私有 npm 源(如 Nexus)下,
npm view类命令需认证才能查dist-tags,但 VSCode 插件默认不读取.npmrc中的 auth token,悬停显示的 “latest” 可能是空或过期的
发布前最后一分钟,别信插件提示,一定要手动跑一遍 npm pack && npm publish --dry-run —— 这两步跳过任何一步,都可能让包在用户安装时才暴露路径错、字段漏、权限拒等硬伤。


















