现代前端开源库工程化实践：基于 unbuild + changesets + GitHub Actions 的全自动化发包工作流

Hey 大家好，我是只爱折腾高效工具、能躺着绝不坐着写代码的 效率喵！🐱✨

作为一个重度「自动化强迫症」患者，我极其反感每次给开源库发版时的一套繁琐流程：本地跑打包、切分支改 package.json 版本号、手写或生成 CHANGELOG.md、提交 Git Tag、最后小心翼翼地敲下 npm publish……一旦中途网络抽风或者漏了打 Tag，血压瞬间拉满！

「偷懒才是第一生产力。」今天喵喵就来给大家安利一套我现在主力开源项目都在用的 现代化工程化全自动发版流：unbuild + changesets + GitHub Actions。

从代码编写到自动推送到 npm，全程只需在终端敲一次确认，剩下的脏活累活全交给机器！

🛠️ 效率喵的神仙武器库

在进入正题前，先简单对比一下为什么选这套组合：

第一步：用 unbuild 实现零心智负担的构建

tsup 很强，但由 Nuxt/UnJS 团队打造的 unbuild 在开发体验（DX）上更是深得我心。

1. 安装依赖

pnpm add -D unbuild typescript

2. 配置 build.config.ts

在根目录建一个配置文件，干净利落：

import { defineBuildConfig } from 'unbuild'

export default defineBuildConfig({
  entries: ['src/index'],
  // 自动生成类型定义文件（.d.ts）
  declaration: true,
  // 清理 dist
  clean: true,
  // 导出 ESM 和 CommonJS
  rollup: {
    emitCJS: true,
  },
})

3. 配置 package.json

unbuild 有个无敌的功能叫做 jiti stub，在开发期间无需频繁重新 build，直接引用源码调试！

{
  "name": "my-awesome-lib",
  "version": "0.1.0",
  "type": "module",
  "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"
    }
  },
  "scripts": {
    "build": "unbuild",
    "dev": "unbuild --stub",
    "prepublishOnly": "pnpm build"
  }
}

💡 喵喵快捷技巧：本地开发关联测试时，跑一次 pnpm dev（启动 stub 模式），其他项目用 pnpm link 连过来后，你改源码对方能实时响应，彻底告别持续 watch 的高 CPU 占用！

第二步：引入 changesets，优雅管理版本与日志

很多团队推行 Conventional Commits（Angular 规范）经常翻车，因为总有人提交形如 fix: bug、update 的无意义信息，导致自动生成的 Changelog 惨不忍睹。

changesets 的思路完全不同：它把版本更新说明当成一种「待办任务」。

1. 初始化

pnpm add -D @changesets/cli
pnpm changeset init

这会在项目根目录生成 .changeset/config.json。我们简单修改一下：

{
  "$schema": "https://unpkg.com/@changesets/config@3.0.0/schema.json",
  "changelog": "@changesets/cli/changelog",
  "commit": false,
  "fixed": [],
  "linked": [],
  "access": "public",
  "baseBranch": "main",
  "updateInternalDependencies": "patch",
  "ignore": []
}

2. 日常开发怎么用？

当你改完了代码，准备提 PR 前，只需在终端敲入：

pnpm changeset

CLI 会交互式询问你：

1. 涉及哪个包？（单包直接回车）
2. 这是 major（破坏性）、minor（新特性）还是 patch（修复补丁）？
3. 请为这次修改写一句人类可读的汇总摘要。

执行完后，.changeset/ 目录下会生成一个 Markdown 碎片文件，直接带着这个文件一起提交 Git。多人协作时不仅不冲突，Reviewer 还能直观看到这次 PR 打算怎么发版。

第三步：让 GitHub Actions 接管一切（终极奥义）

现在万事俱备，只欠自动化东风！我们要达成的效果是：

1. 代码合并到 main 分支。
2. Actions 检测到有 changeset 碎片，自动提一个名为「Version Packages」的 PR，把版本号自增和 Changelog 都写好。
3. 当你审核完毕，将这个发版 PR 合并进 main 分支，Actions 立即 自动打包、发布到 npm、生成 GitHub Release 并打 Tag！

1. 配置 npm Token

• 登录 npm，在个人中心生成一个 Automation 类型的 Access Token。
• 打开你的 GitHub 仓库 -> Settings -> Secrets and variables -> Actions -> 添加 NPM_TOKEN。

2. 创建 GitHub Actions 工作流

新建 .github/workflows/release.yml：

name: Release

on:
  push:
    branches:
      - main

concurrency: ${{ github.workflow }}-${{ github.ref }}

permissions:
  contents: write
  pull-requests: write
  id-token: write

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repo
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Install pnpm
        uses: pnpm/action-setup@v3
        with:
          version: 8

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'pnpm'

      - name: Install Dependencies
        run: pnpm install --frozen-lockfile

      - name: Create Release Pull Request or Publish
        id: changesets
        uses: changesets/action@v1
        with:
          # 触发真实发布时跑的命令
          publish: pnpm changeset publish
          # 触发版本自增时跑的命令
          version: pnpm changeset version
          title: "chore(release): version packages"
          commit: "chore(release): version packages"
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}

🐾 丝滑的日常流转体验

配置完成后，以后的开源维护流程彻底变成了这几步：

1. 改代码：尽情享受 unbuild --stub 带来的秒级本地联动体验。
2. 提更改：终端敲 pnpm changeset，打字写一条给用户看的更新说明，提交代码并推到 GitHub 提 PR。
3. 合并：PR 被合入 main 分支后，GitHub Actions 启动。它会自动帮你提一个新的 Release PR，长这样：

   PR Title: chore(release): version packages
   PR Description: 自动整合了上次发版以来的所有变更记录，甚至 CHANGELOG.md 都给你渲染得清清楚楚。

4. 一键发版：这个 PR 允许你积攒多个功能。等觉得合适了，直接点击「Merge Pull Request」！
5. 收工躺平：Actions 会自动识别这个特殊的发布提交，执行 unbuild 编译，然后一键推送至 npm 官方源，同时 GitHub 的 Releases 页面也会打上漂亮的 Tag。

🐱 喵喵的效率总结

• 省心度：⭐⭐⭐⭐⭐（再也没在发版时搞错过 Git Tag）
• 优雅度：⭐⭐⭐⭐⭐（生成的 Changelog 条理分明，没有乱七八糟的 commit 垃圾）
• 速度：⭐⭐⭐⭐（unbuild + pnpm 构建神速，CI 基本两分钟内跑完）

工程化的本质就是把容易犯错的重复人肉劳动标准化、自动化。这一套工作流不论是维护个人精致的小玩具，还是上百个包的巨大 Monorepo 库，都能游刃有余。

快给你的开源仓库装上这套「涡轮增压引擎」吧，有任何配置问题欢迎随时来找喵喵交流探讨！🐾✨