使用 github actions 实现 npm 包自动化发布

鉴于我发布/即将发布的 npm 包越来越多，我决定用 github 的 actions 功能来实现 npm 包自动发布，过程也比较顺利，遂决定写一篇流水账记录下自动发布的实现，方便以后用到的时候翻阅。

起步

以 react-m-editor 这个组件为例子，发布过程一般分位两步以下两步：

1. 打包组件，发布 npm 组件
2. 打包示例，发布 github page 示例界面

下面我们就按照上面两个步骤来实现目标。
我们先在github网站上的项目下找到 Actions 菜单栏，这边官方会提供一堆 Workflow 供我们选择，我们从中找到一个 Publish Node.js Package，会自动帮我们生成一份配置文件 .github/workflow/npm-publish.yml，内容如下：

# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages

name: Node.js Package

on:
  release:
    types: [created]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
      - run: npm ci
      - run: npm test

  publish-npm:
    needs: build
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
          registry-url: https://registry.npmjs.org/
      - run: npm ci
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

// ... 还有一部分用于发布 githua package 的代码
// ... 因为用不到所以直接将这部分删除了

下面我们根据具体的发布步骤修改配置文件。

触发事件配置

一般的发布脚本都会有一个触发事件，github actions 是通过脚本中的 on 字段判断的，默认的触发事件是创建版本：

on:
  release:
    types: [created]

我比较习惯使用 pull_request 发布，所以在这里我将它改成了其他分支发布 pr 到 main 分支时发布：

on:
  pull_request:
    branches:
    - main

发布 npm 组件

之前发布 npm 包都是本地打包成组件后登录 npm 账号运行 npm publish 发布，生成的配置文件中已经有类似的功能了，但是还有一些配置需要修改。
首先示例配置文件用的包管理工具是 npm，而我的项目用的是 yarn，经过 查阅资料 发现 actions/setup-node 这个工具支持 yarn ：

Supported package managers are npm, yarn, pnpm (v6.10+).)

直接将 npm ci 修改成 yarn install。
生成的配置文件中的 build 部分是单元测试用的，这个组件没写测试代码😓，所以这块直接删除。而在发布的配置中，缺少了打包的选项，所以还得添加 yarn build。最后发布部分配置具体如下：

publish-npm:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
          registry-url: https://registry.npmjs.org/
      - run: yarn
      - run: yarn build
      - run: yarn publish
        env:
          NODE_AUTH_TOKEN: ${{secrets.npm_token}}

这边有配置一个 secrets.npm_token，这是一个 npm 生成的用来做登录认证的 token，配置步骤如下：

在 npm 官网生成 token

1. 登录 npm 官网，在右上角的头像下拉选项中选中 Access Tokens 进入界面
2. 点击 Generate New Token 按钮，选择 Automation 或者 publish 选项，再点击 Generate Token 按钮
3. 界面提示 Successfully generated a new token! ，复制生成的 token

在 github 中登记 token

1. 进入 github 的 项目目录 ，选择 Settings 菜单进入项目的设置界面
2. 在侧边栏选中 Secrets 进入该界面，选中 New repository secret 按钮，输入表单信息，Name 为 NPM_TOKEN，Value 为刚刚复制的 token，最后点击 Add Secret 按钮添加完成

步骤结束后，提交一个 pr 测试发布，在 Actions 菜单下面可以查看完整的日志，发布成功。

发布 github page

这里用到了 peaceiris/actions-gh-pages 插件，下面直接贴配置代码

  create-githubpage:
    needs: publish-npm
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: 14
      - name: page build
        working-directory: ./example
        run: |
            yarn
            yarn add react-m-editor
            yarn build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          personal_token: ${{ secrets.PERSONAL_TOKEN }}
          publish_dir: ./example/build

这里要注意几个问题

1. 脚本运行的位置是在项目目录下的 example 文件夹中，要通过设置 working-directory 来配置工作文件夹，~而不是用命令行去 进入文件夹~。
2. 组件和示例都是用了 react hook 去实现，本地打包组件后后再用打包好的组件去打包示例，会有 多个react版本问题，开发环境时可以通过 link 解决。在这里可以直接 yarn add react-m-editor 安装最新版本的组件，之后打包的代码就不会出现这个报错。

因为我们打包后的代码是要上传到 github 上的，所以还有一个 github 的登录认证问题。actions-gh-pages 提供了三中登录认证：

认证	私有项目	公共项目	协议	是否需要设置
github token	✅	✅	HTTPS	不需要
deploy_key	✅	✅	SSH	需要
personal_token	✅	✅	HTTPS	需要

设置认证为 github_token

无需设置，按以下配置即可，点击查看设置文档。

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    github_token: ${{ secrets.GITHUB_TOKEN }}
    publish_dir: ./example/dist // 打包后静态界面的路径

设置认证为公私钥对 deploy_key

点击查看如何配置公私钥
在本地终端运行以下命令行生成公私钥

ssh-keygen -t rsa -b 4096 -C "$(git config user.email)" -f gh-pages -N ""
# You will get 2 files:
#   gh-pages.pub (公钥)
#   gh-pages     (私钥)

进入 github网站 的项目目录下，选择 Settings 菜单，选择左侧的 Deploy keys 菜单，点击 Add deploy key 按钮，进入新增界面，勾选上 Allow write access，输入 Title，然后将本地生成的 gh-pages.pub 的内容复制到 Key 输入框中，点击 Add key 按钮，添加公钥成功。
选择左侧 Secrets 菜单，新增一个 Name 为 ACTIONS_DEPLOY_KEY 的 Repository secrets，Value 为 gh-pages 的内容，添加公钥成功。
配置文件中相关部分配置如下：

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    deploy_key: ${{ secrets.ACTIONS_DEPLOY_KEY }}
    publish_dir: ./example/dist  // react-m-editor 打包后的项目文件在这个文件夹中

设置认证为 personal_token

进入 Settings/Settings Developer settings 界面，选择左侧的 Personal access tokens 菜单，点击 Generate new token 按钮，Node 输入 git-page key （这个自己取名），Expiration 选一个过期时间，这边我选择了 No Expiretion（用不过期），勾选 repo 选项，拥有代码的读写权限，最后点击 Generate token 按钮生成 token。
复制生成的 token，进入项目界面-> Settings -> Secrets，新增一个 Name 为 PERSONAL_TOKEN 的 Repository secrets，Value 为刚刚复制的 token 。
配置文件中的相关配置如下：

- name: Deploy
  uses: peaceiris/actions-gh-pages@v3
  with:
    personal_token: ${{ secrets.PERSONAL_TOKEN }}
    publish_dir: ./example/dist

注意：以上三中认证仅需配置一种

提交 pr 后测试，发布 github pages 成功。
点击查看项目完整的发布脚本配置。

参考

actions-gh-page 文档