从零到一：实现 Changesets 自动化发版全流程

date
Feb 26, 2025
slug
auto-changesets
status
Published
tags
Technology
summary
本文详细介绍了如何从零开始实现 Changesets 的自动化发版流程，涵盖从初始化 Monorepo 项目到配置自动化工作流的全过程。通过合理配置 GITHUB_TOKEN 和 NPM_TOKEN，结合 GitHub Action 和 Changesets 的强大功能，我们成功搭建了一套高效的自动化发版系统。
type
Post
在上篇文章中，我们对 Changesets 的基本使用进行了简单介绍。本文将在此基础上，进一步深入讲解如何实现 Changesets 的自动化流程，帮助你更高效地管理版本发布。
 

前置准备

初始化 Monorepo 项目

在 core 和 plugin-dashboard 两个库中，分别提供最基础的 package.json 信息：
 
然后在 core 和 plugin-dashboard 两个库中提供最基础的 package.json 信息:
package.json
 

初始化 Changesets

接下来，安装并配置 Changesets：
此时，项目结构变为：
 
同时，为 Changesets 添加一些便捷的 scripts：
packages.json
 
现在，你可以通过运行 pnpm pub:changeset 来为库添加变更日志。例如：
随后，在 .changesets 目录下会生成一个 changelog 文件。
 

自动化流程

假设项目分支结构如下：
整体流程概述如下：
  1. 在 develop 分支上开发功能，并进行测试。
  1. 完成功能开发后，基于 main 分支新建一个 release/xxx 分支，将需要发布的功能合并进来。
      2. 自动化流程细节：
    1. 基于 release/xxx 分支创建一个 changelog/xxx 分支。
    2. 在该分支上执行 pnpm pub:version，生成版本信息。
    3. 创建一个 PR，包含所有需要发布库的 CHANGELOG，并将此分支合并到 release/xxx 上。
  1. 在 release/xxx 分支测试无误后，将其合并到 main 分支。
      2. 自动化流程细节：
    1. 执行 pnpm pub:build，对库的内容进行打包。
    2. 执行 pnpm pub:release，对库进行发布。
主要的自动化流程集中在 release/xxx 和 main 分支上，接下来进入实操环节。
 
首先，将需要用到的 token 进行配置
  • GITHUB_TOKEN：用于 changeset 生成 PR。
  • NPM_TOKEN：用于发版。
 

GITHUB_TOKEN 的配置

在 changesets/action 中，会创建一个版本更新 PR，这需要借助 GITHUB_TOKEN 来获取相应权限。
进入用户个人设置中心，依次点击 Setting > Developer Settings > Personal access tokens，来添加一个新的 token。
notion image
点击按钮新增 token 。
notion image
生成后，会看到对应的 token（请妥善保存，一旦丢失，只能删除后重新配置）。
notion image
 

将 token 添加到 environment secrets（环境密钥）

接着，将该 token 配置到项目的环境密钥中，操作步骤如下：
notion image
点击按钮添加 environment secret。
notion image
填写名称和 token，完成配置。
 

NPM_TOEKN 的配置

登录 npm 官网，找到 Access Token 目录。
notion image
点击按钮创建 token。
notion image
token 的配置界面与 GitHub 类似：
notion image
生成后，在页面顶部可以看到你创建的 token。
notion image
 
按照之前配置 GITHUB_TOKEN 的方法，将 NPM_TOKEN 也配置到项目的环境密钥中。
 
在配置过程中，可能会遇到以下问题：

问题：@xxx/xxx 发布错误

例如，当你尝试发布一个名为 @easyeditor/core 的库时，可能会遇到发布失败的情况，并提示如下错误：
notion image
原因在于，以 @xxx 开头的库，需要先在 npm 中创建对应的组织，才能正常使用。
解决方法如下：
  1. 登录 npm 官网，进入组织创建页面。
  1. 填写相关信息，创建组织，其中名称需与 @xxx 中的 xxx 保持一致，即对应组织名。
notion image
这里的名称要对应 @xxx 中的 xxx，也就是组织名才行。
notion image
 
创建完成后，记得将自己邀请到该组织中，然后再尝试重新发布。
 

自动化实现：Github Action + changesets/action

在根目录下创建如下两个自动化工作流文件：
 
关于 Github Action 的具体使用细节在此不做过多展开，但会详细讲解这两个工作流文件的内容。

version 工作流

其中，secrets.PERSONAL_GITHUB_TOKEN 对应项目环境密钥中配置的 GITHUB_TOKEN 名称。
 

release 工作流

 
将上述 workflows 文件推送到仓库后，创建对应的 release/xxx 分支，即可触发相应的工作流。
在 version 工作流执行过程中，可以看到如下内容：
notion image
完成后，在 PR 中会看到一条新的合并请求：
notion image
合并完成后，对 release/xxx 分支进行测试，确认是否可以进行发版。
准备就绪后，将 release/xxx 分支合并到 main 分支：
notion image
同时，会触发发版的工作流：
notion image
至此，整个自动化发版流程便完成了。
 
在实践过程中，可能会遇到以下问题：

问题1：remote: Permission to xxx.git denied to github-actions[bot].

原因：工作流缺乏创建 PR 的权限。
这里有两种方式去解决：
  1. 在仓库的设置里为工作流添加权限。
      2. notion image
  1. 在工作流文件中配置权限，即上文中提到的 permissions: write-all。
      2. 如果需要，也可以专门指定特定的权限，例如：
 

问题2：error TypeError: Cannot read property 'prerelease' of null

关联 ISSUE：
  1. Fixed the prerelease version parse by vzt7 · Pull Request #847 · changesets/changesets
  1. Fix issue with bumping packages without `package.json#version` by Andarist · Pull Request #705 · changesets/changesets
原因：在发布 prerelease 版本时，项目库中可能存在 examples/demos 等案例项目，这些项目设置了 private: true，但未设置 version，从而导致该错误。
解决方法：为案例项目添加 version 字段，虽然它不会生效（记得在 .changeset/config.json 中忽略该项目），但可以避免这个错误。
 

参考项目

为了更好地理解和实践上述自动化发版流程，你可以参考以下已经成功实现的项目：
Easy-Editor/EasyEditor: A cross-framework low-code engine with scale-out design
通过该项目，你可以直观地看到 Changesets 自动化发版流程在实际项目中的应用，从而更好地将其应用到自己的项目中。
 

© JinSo 2021 - 2025