组件的发布

构建完成之后，下一步才是发布。

但“发布”不只是执行一次 npm publish，更准确地说，它是在回答这几个问题：

• 你的包要以什么入口暴露给使用者
• 使用者会拿到哪些文件
• 不同模块系统怎样正确解析你的包
• 发布出去之后，别人怎样稳定安装、引用和升级

如果这些问题没处理好，哪怕你组件本身写得不错，包的使用体验也会很差。

发布流程

发布到 npm 源，本质上是为了分发。

之前我们已经构建出了产物，现在要把这些产物以合适的 package.json 描述发布出去。

你可以把发布理解成两层：

1. 产物层：dist 里到底有哪些文件
2. 元数据层：package.json 如何告诉外界这些文件该怎么用

先把入口讲清楚

像之前的产物目录：

index.css
index.d.ts
index.js
index.umd.cjs

你通常会在 package.json 中这样配置：

{
  "name": "ice-ui",
  "version": "0.0.0",
  "type": "module",
  "files": ["dist"],
  "main": "./dist/index.umd.cjs",
  "module": "./dist/index.js",
  "exports": {
    ".": {
      "import": "./dist/index.js",
      "require": "./dist/index.umd.cjs"
    },
    "./style.css": "./dist/index.css"
  }
}

这里最重要的不是背字段，而是理解各字段在告诉消费者什么：

• files：发布时哪些文件会被带上
• main：传统 CommonJS / 工具兼容入口
• module：ESM 入口
• exports：更现代、更明确的公开出口声明

为什么 exports 很重要

现代包分发里，exports 通常比单纯依赖 main / module 更可靠。

因为它能明确限制：

• 哪些路径允许外部访问
• import 和 require 分别走哪里
• 样式、子路径、类型等是否显式暴露

这能减少“用户绕过公开 API 直接 import 内部文件”的问题，也能降低后续重构时的兼容成本。

发布到 npm 源

在注册 npmjs.com 之后，创建 Access Token，你就可以用这个 token 发布包。

这个 token 一般会保存在全局 .npmrc 中。

配置完成后，执行：

npm publish

即可发布到公有 npmjs.com 源。

发布前一定要先做 dry run

比起直接发布，更建议先执行：

npm publish --dry-run

它能帮助你确认：

• 到底哪些文件会被发布
• 有没有把源码、测试、临时文件意外带进去
• dist 目录是否真的齐全

这是最便宜的一次发布前检查。

指定 npm 源

可以通过 package.json 中的 publishConfig 指定发布源：

{
  "publishConfig": {
    "access": "restricted",
    "registry": "http://your.self.npm.org/"
  }
}

这在私有源、企业源、内部组件库场景里尤其常见。

发布成功之后要看什么

你可以在：

https://www.npmjs.com/package/<your-package-name>

看到你发布的包。

这里 <your-package-name> 就是你在 package.json 中声明的 name。

但发布成功不等于“可用性就验证完了”。更稳妥的做法是再确认三件事：

1. 能否被全新项目正常安装
2. ESM / CJS 入口是否都能解析
3. 样式入口和类型声明是否按预期生效

常见发布问题

1. 入口字段写对了，但文件没进包

这通常是 files、.npmignore 或构建输出目录没对齐。

2. 本地能用，发布后不能用

常见原因是：

• 本地依赖被误当成生产依赖
• peerDependencies 没声明清楚
• 入口路径写错

3. 类型声明缺失

组件库如果没有把 .d.ts 一起发布，使用体验会立刻下降一大截。

4. 样式没暴露

如果 CSS 需要显式导入，但你没有在 exports 中暴露对应路径，使用者就会很困惑。

关于版本和升级

当你的组件库开始被真实项目依赖之后，发布就不再只是技术动作，而会变成兼容性承诺。

这意味着你至少要有：

• 清晰的版本号策略
• 对 breaking change 的意识
• 对外可读的变更说明

否则用户能装上包，但不敢升级。

进阶：npm 页面展示也很重要

package.json 里很多字段会影响 npmjs 页面展示和搜索结果，例如：

• description
• keywords
• repository
• homepage
• license

例如：

{
  "repository": {
    "type": "git",
    "url": "https://github.com/sonofmagic/deep-in-vue.git"
  }
}

会影响页面中的 Repository 展示。

{
  "homepage": "https://deep-in-vue.icebreaker.top"
}

会影响页面中的 Homepage 展示。

这类字段看起来不影响运行，但会影响包的可信度、可发现性和使用者理解成本。

发布前检查清单

在真正发布前，建议至少确认：

1. dist 产物完整
2. package.json 入口字段正确
3. npm publish --dry-run 结果符合预期
4. 类型、样式、子路径导出都能正常访问
5. 版本号和变更说明已经准备好

做到这一步，发布才算真正稳妥。