企业官网建设流程全解析

p5.js 发布流程全解析：从 semver 标签到 GitHub Release、NPM、官网与 CDN 的自动化流水线

【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js

本文是 p5.js 开源仓库贡献者文档 contributor_docs/release_process.md 的深度解读与实战指南。作为维护者或贡献者，你只需在本地执行四条 git/npm 命令，即可借助 GitHub Actions 完成从版本号提升、测试、构建到 GitHub Release、NPM 发布、官网数据同步与 CDN 分发的完整发布链路。读完本文，你将掌握 p5.js 官方发布机制的整体设计、每一步在 CI 中的具体实现、安全令牌的配置方法，以及如何在本地用 act 演练发布流程。

总体思路：一切自动化，一切在 CI 中完成

p5.js 的发布流程遵循一个核心设计原则：把尽可能多的发布步骤集中到一个地方——GitHub Actions CI 环境。维护者在本地只做最少、最不容易出错的操作（切分支、打版本号、推送），其余所有环节——运行测试、构建产物、创建 GitHub Release、发布到 NPM、更新官网仓库、同步 Bower 仓库——全部由 CI 工作流在云端完成。

原文档还明确了一条架构约定："If a new step that is only run on release is required, it should probably be defined in the CI workflow and not as part of the build configuration."——即任何只在发布时执行的新步骤，都应该定义在 CI 工作流中，而不是塞进构建配置里。这保证了日常构建与发布构建的职责边界清晰，也便于维护者集中审查发布行为。

版本号策略：遵循 SemVer

发布流程以 SemVer（语义化版本） 为版本管理规范，版本号格式为MAJOR:MINOR:PATCH（文档原文写作MAJOR:MINOR:PATCH，即常见的MAJOR.MINOR.PATCH）：

• MAJOR（主版本号）：存在不兼容的 API 变更时递增，如 p5.js 2.x 相对 1.x 的升级；
• MINOR（次版本号）：以向后兼容的方式新增功能时递增；
• PATCH（修订号）：向后兼容的缺陷修复时递增。

在当前仓库中，package.json的version字段为2.3.1，而.github/workflows/release-workflow-v1.yml与.github/workflows/release-workflow-v2.yml分别监听v1.*.*与v2.*.*两种标签模式，这也印证了 p5.js 采用语义化版本并同时维护 1.x 与 2.x 发布通道的现状。

发布前置条件

在触发一次正式发布之前，需要确认以下条件全部满足：

安全令牌：两个必须预先设置的仓库 Secret

发布工作流需要两个 GitHub 仓库级加密 Secret（repository secrets），缺一不可。这两个令牌的职责有严格区分：

NPM_TOKEN：负责发布到 NPM

• 按 NPM 官方文档 创建具备read and publish权限的令牌；
• 令牌所属的 NPM 账号必须对p5这个包拥有发布权限；
• 在 CI 中，该令牌被注入到发布步骤（JS-DevTools/npm-publishaction）的token参数中。从源码看，v1 与 v2 工作流都在env层声明了INPUT_TOKEN: ${{ secrets.NPM_TOKEN }}，并在 NPM 发布步骤中显式使用。

ACCESS_TOKEN：负责跨仓库写入

• 这是一个personal access token（PAT），属于一个对p5.js、p5.js-website、p5.js-release三个仓库都有访问权限的账号；
• 生成时（参考 GitHub PAT 创建指南）Scope 只勾选repo和workflow两项，不要多给；
• 官方强烈建议使用组织专用账号而非个人账号，并将该账号的写权限严格限制在所需的三个仓库上，以降低令牌泄露时的爆炸半径。

在 CI 中，ACCESS_TOKEN用于actions/checkout克隆processing/p5.js-website与processing/p5.js-release仓库，以及ad-m/github-push-action将更新后的内容推送回对应仓库。

发布操作：本地只需四步

整个发布动作在本地浓缩为四条命令（在仓库根目录执行）：

$ git checkout main $ npm version [major|minor|patch] # Choose the appropriate version tag $ git push origin main $ git push origin v1.4.2 # Replace the version number with the one just created above

各命令的作用与注意点：

1. git checkout main：先切到主干分支，确保发布基于最新主干代码；
2. npm version [major|minor|patch]：根据变更类型选择major、minor或patch。该命令会同步完成三件事——更新package.json的version字段、生成对应的 git tag（例如v1.4.2）、创建一次版本提交；
3. git push origin main：推送主干分支，使package.json中的新版本号进入远端；
4. git push origin vX.Y.Z：推送刚创建的版本标签。注意推送标签这一步是触发 CI 发布工作流的开关——工作流的触发条件on: push: tags正是匹配这个标签。

执行完毕后，真正的发布步骤全部在 GitHub Actions CI 上运行，本地无需再做任何操作。

监控与结果核验

在 Actions 页面跟踪进度

推送标签后，打开 p5.js 仓库的Actions标签页，寻找名为"New p5.js release"（v1 工作流）或"New p5.js 2.x release"（v2 工作流）的 job，点击进入即可查看详细的运行日志，包括测试输出、构建产物、GitHub Release 创建与 NPM 发布结果。

逐渠道核验结果

发布 job 完成后，需要按以下顺序核验各发布渠道：

1. GitHub Release：在 Releases 页面会看到一个draft（草稿）状态的新版本——这是softprops/action-gh-release以draft: true创建的结果。维护者应打开草稿，必要时修订自动生成的 changelog，然后手动点击 Publish 正式发布；
2. NPM：在 NPM 的p5包页面确认最新版本号已出现；
3. 官网：p5.js 官网的更新由其自身的构建与部署 job 完成（可在p5.js-website仓库的 Actions 页面监控），完成后在官网 Downloads 页面核对最新版本号；
4. CDN：CDN 会自动从 NPM 拉取新版本，通常需要一两天的延迟，无需任何人工操作。

幕后机制：CI 工作流到底做了什么

原文档提到触发工作流的是.github/workflows/release.yml，而在当前仓库中，实际落地为两份按主版本区分的文件：

• .github/workflows/release-workflow-v1.yml：监听v1.*.*与v1.*.*-*标签，负责 1.x 版本线；
• .github/workflows/release-workflow-v2.yml：监听v2.*.*与v2.*.*-*标签，负责 2.x 版本线，并额外增加 TypeScript 类型生成与校验步骤。

另外，仓库根目录的 .github/release.yml 是 GitHub 自动生成 Release Notes 的配置：默认排除Dependencies标签与dependabot账号的提交，并将变更分类为 "What's Changed 🎊" 与 "New Contributors 💗" 两个板块（后者收录allcontributors账号的贡献者条目）。

触发条件与预发布判断

工作流由push到匹配v*.*.*模式的标签触发（同时兼容v*.*.*-*形式的预发布标签）。触发后首先进行预发布判断：

- name: Check prerelease id: semver run: | if [[ "${{ github.ref_name }}" == *"-rc"* ]]; then echo "is-prerelease=true" >> $GITHUB_OUTPUT else echo "is-prerelease=false" >> $GITHUB_OUTPUT fi

如果标签名包含-rc后缀，则判定为预发布（is-prerelease=true）。这一判断会向下游传递两个关键影响：

• GitHub Release 会以prerelease: true创建（v1 与 v2 工作流均是如此）；
• 涉及外部仓库写入的步骤（NPM 发布、官网更新、Bower 同步）会通过if: ${{ steps.semver.outputs.is-prerelease != 'true' }}全部跳过，避免预发布版本污染正式渠道。

五大步骤的源码级还原

综合 v1/v2 两份工作流，触发后的完整执行序列如下：

步骤 1：环境准备与质量门禁

1. actions/checkout克隆仓库（注意设置persist-credentials: false，避免将凭据带入后续步骤）；
2. actions/setup-node配置 Node.js（v1/v2 均固定为 Node 22，v1 注释明确说明"Keep at 22 purposefully for v1"）；
3. 从标签提取版本号：version=$(echo ${{ github.ref_name }} | cut -c 2-)，即去掉标签首字母v；
4. 记录当前日期（用于版本横幅）；
5. npm ci安装依赖（CI 模式）；
6. npm test运行测试——这是发布前的质量门禁，测试失败则流程中止。v2 工作流运行npm test -- --project=unit-tests，并在npm run build后追加npm run generate-types（生成types/下的 TypeScript 声明）与npm run test:types（校验类型），确保 2.x 发布的类型文件正确；
7. npm run build执行构建。

从 package.json 可见，构建脚本为rolldown -c，对应 rolldown.config.js：产物包含lib/p5.js（IIFE 格式，带版本横幅/*! p5.js vX.Y.Z ... */）、lib/p5.min.js、lib/p5.esm.js、lib/p5.esm.min.js，以及lib/p5.webgpu*.js等 WebGPU 附加模块和dist/目录的 ESM 源码构建。版本号通过replacePlugin中的VERSION_WILL_BE_REPLACED_BY_BUILD: pkg.version注入到源码中，横幅日期则通过new Intl.DateTimeFormat('en-US', ...)生成。

步骤 2：打包发布文件

- run: mkdir release && mkdir p5 && cp -r ./lib/* p5/ - name: Create release zip file uses: TheDoctor0/zip-release@... with: type: zip filename: release/p5.zip path: ./p5/* - name: Copy release files run: cp lib/p5.js lib/p5.min.js lib/addons/p5.sound.js lib/addons/p5.sound.min.js release/

先将lib/下所有产物复制到p5/目录，打包成release/p5.zip作为压缩包附件；再把核心分发文件（v1 为p5.js、p5.min.js及p5.sound.js两个 addons；v2 为p5.js、p5.min.js、p5.esm.js）单独复制到release/目录，作为 GitHub Release 的独立附件。

步骤 3：创建 GitHub Release 并发布 NPM

• 使用softprops/action-gh-release创建draft（草稿）Release：draft: true、prerelease由步骤 1 的预发布判断决定、generate_release_notes: true让 GitHub 依据 .github/release.yml 自动生成 Release Notes、附件为release/*；
• 使用JS-DevTools/npm-publish发布到 NPM。v1 工作流中此步骤带if: is-prerelease != 'true'条件；v2 工作流则始终执行，但通过tag: latest|beta区分正式版与 beta 通道——正式版走latest，预发布版走beta。

步骤 4：更新 p5.js 官网仓库

1. 用ACCESS_TOKEN通过actions/checkout克隆processing/p5.js-website（v1 推送到v1分支，v2 推送到main分支，fetch-depth: 0保证完整历史）；
2. npm install后依次执行官网自身的构建脚本：build:p5-version、build:contributor-docs、build:contributors、build:reference、build:search；
3. 以github-actions[bot]身份提交，commit message 为Update p5.js to ${{ github.ref_name }}；
4. 用ad-m/github-push-action配合ACCESS_TOKEN推送回官网仓库。

原文档中提到的"复制data.json、data.min.json、p5.min.js、p5.sound.min.js、更新data.yml与en.json"等操作，在当前实现中已整合进官网仓库的build:p5-version等构建脚本——参考文档数据生成逻辑可参见 utils/convert.mjs，它读取docs/data.json并输出docs/reference/data.json与docs/reference/data.min.json（以及用于参数校验的docs/parameterData.json），这些数据文件即官网参考文档的数据来源。

步骤 5：同步 Bower 发布仓库

1. 用ACCESS_TOKEN克隆processing/p5.js-release（Bower 发布仓库）到bower/目录；
2. 复制库文件：cp lib/*.js bower/lib/与cp lib/addons/* bower/lib/addons/；
3. 以 bot 身份提交并推送到master分支（该仓库默认分支为master）。

本地测试发布流程：用 act 模拟 CI

由于发布步骤全部运行在 CI 中，本地测试并不直观。官方推荐使用 act 在本地模拟 GitHub Actions 的执行——发布工作流开发期间正是用这种方式测试的。不过有两个注意事项：

1. 测试步骤可能不会完整运行：完整测试需要 mocha/Chrome 浏览器测试环境所依赖的系统组件，本地往往缺失。通常需要先用apt安装若干系统依赖，再配置其余环境。建议紧盯错误信息，它会明确提示缺少哪些包；
2. 必须注释掉涉及远程推送的步骤：工作流中的"克隆并推送p5.js-website/p5.js-release"等步骤会真实改动远端仓库，本地演练前务必注释掉，以免意外推送未经验证的改动。

由于 act 的具体操作步骤会随工作流定义演进而变化，官方文档仅给出上述方向性说明，精确步骤建议以当时的工作流文件与 act 文档为准。

关键要点回顾

• 触发即发布：git push origin vX.Y.Z是唯一开关，其余全部交给 CI；
• 质量门禁前置：npm test（v2 还包含类型生成与校验）不通过则不会产生任何发布产物；
• 草稿机制：GitHub Release 以 draft 创建，changelog 可人工修订后再正式发布；
• 预发布隔离：-rc标签走 prerelease 通道，且跳过 NPM 正式版、官网与 Bower 的更新；
• 双令牌隔离：NPM_TOKEN只管 NPM 发布，ACCESS_TOKEN只管跨仓库写入，权限最小化；
• 外部仓库写入集中在 CI：官网（p5.js-website）与 Bower（p5.js-release）的更新均由工作流内的专用步骤完成，不在本地执行。

【免费下载链接】p5.jsp5.js is a client-side JS platform that empowers artists, designers, students, and anyone to learn to code and express themselves creatively on the web. It is based on the core principles of Processing. Looking for p5.js 2.0? http://beta.p5js.org项目地址: https://gitcode.com/GitHub_Trending/p5/p5.js