npm已经成为JavaScript生态事实上的包管理标准，无论是发布一个工具函数还是维护一套企业内部组件库，开发者都需要理解npm包从初始化到发布维护的完整链路。很多人只关注npm install和npm run dev，但真正决定一个npm包质量的，是package.json中的入口配置、发布白名单、版本号策略以及依赖类型的选择。本文围绕这些关键环节展开，帮助开发者建立系统化的npm发布与维护能力。
一、package.json字段设计决定包的解析结果
npm包的最基本元数据都集中在package.json中，其中name和version是发布时必须存在的字段。name需要遵循小写、短横线分隔的规则，不能包含空格或大写字母；version必须符合语义化版本规范，由主版本、次版本和修订号组成，例如1.2.3。除了这两个必填项，main字段曾长期作为包的默认入口，但在现代前端工程中，仅配置main已经不足以覆盖所有消费场景。
更推荐的做法是同时声明module和exports。module字段通常指向ES模块版本的入口文件，让打包工具在支持tree-shaking时优先使用；exports字段则提供了更精细的入口映射能力。例如下面这个配置，可以让import和require分别加载不同产物，同时限制了包内其他文件被外部直接引用：
{
"name": "my-utils",
"version": "1.0.0",
"main": "./dist/index.cjs",
"module": "./dist/index.mjs",
"types": "./dist/index.d.ts",
"exports": {
".": {
"import": "./dist/index.mjs",
"require": "./dist/index.cjs",
"types": "./dist/index.d.ts"
}
},
"files": [
"dist"
]
}
这里注意，exports一旦声明，它会覆盖main和module的默认解析规则，外部通过包名子路径访问时也必须在exports中显式暴露，否则会返回ERR_PACKAGE_PATH_NOT_EXPORTED。files字段同样重要，它决定npm publish时哪些文件会被上传。如果没有files白名单且缺少.npmignore，npm会使用.gitignore作为回退策略，有时会把源码、测试文件甚至构建脚本一起发布出去。因此建议显式声明files，只发布dist目录和必要的README文件。
二、发布流程与版本策略怎么选
本地开发完成后，正式发布前应当先使用npm pack命令生成压缩包并检查内容。npm pack会按照files、.npmignore和package.json中的配置打包，加--dry-run参数可以只显示将要包含的文件列表而不实际生成tgz压缩包。这个动作能有效避免把.env、测试快照或源码map无意中带上线。
发布公共包到npm官方源时，需要先执行npm login完成身份认证。如果包名以@scope开头，默认发布为私有包，需要携带--access public才会作为公共包发布；普通包名则默认公共。建议在package.json中通过publishConfig设置registry和access，避免每次手动传参。例如企业内部私有源可以写成：
{
"publishConfig": {
"registry": "https://registry.npmjs.org/",
"access": "public"
}
}
版本策略上，npm version命令可以自动更新版本号并在Git中打标签。patch用于修复bug，minor用于向后兼容的新功能，major用于不兼容的API变更。如果处于测试阶段，可以采用0.x版本或预发布标签，例如3.0.0-beta.1。发布预发布版本时使用npm publish --tag beta，这样安装者默认不会拿到beta版本，只有显式执行npm install my-package@beta才会命中。当一个旧版本出现严重问题时，npm deprecate比npm unpublish更安全，因为unpublish在npm官方源上有时间限制，且已经被其他项目锁定的版本一旦被移除会直接导致安装失败。
三、依赖类型选择与常见避坑建议
npm包的依赖类型直接影响到消费者的安装行为和最终产物。dependencies用于运行时必需依赖，消费者安装你的包时会自动安装这些依赖；devDependencies只在包自身开发、构建和测试时使用，不会传递给消费者；peerDependencies用于声明宿主环境应当提供的依赖，典型场景是React组件库、Vue插件或Webpack loader。把本应属于peerDependencies的大型框架写进dependencies，可能导致项目中同时存在两份React实例，触发Hooks状态异常或Vue组件上下文错乱。
开发组件库或插件时，建议把React、Vue、webpack这类宿主依赖放入peerDependencies，并在peerDependenciesMeta中标记为可选，或通过engines约束Node版本。例如：
{
"peerDependencies": {
"react": ">=17.0.0"
},
"peerDependenciesMeta": {
"react": {
"optional": false
}
},
"engines": {
"node": ">=14.0.0"
}
}
另外，开发库时应慎重提交package-lock.json。应用项目提交锁文件可以锁定依赖版本，保证部署一致性；但库的package-lock一般不会影响消费者安装结果，反而会随包发布增加内容。可以使用.npmignore或files白名单排除它。本地调试包时，npm link会创建全局符号链接，让目标项目直接引用当前开发目录。这在开发阶段很方便，但完成后要记得npm unlink，否则后续安装的正式版本可能被残留的链接覆盖，出现修改不生效或路径错乱的问题。
还有几个高频坑点：不要在npm包中硬编码绝对路径，尤其是Windows路径C:\Users\xxx这种本机信息；不要在prepublishOnly脚本里执行需要网络请求的测试命令，会导致发布流程脆弱；开启双因素认证2FA后，CI自动发布需要使用Automation类型的访问令牌，而不能用普通登录态；最后，每次提升主版本前，先在README或CHANGELOG中说明迁移步骤，能够显著降低使用者升级成本。