• 开发工具
• 前端

本文面向 speedscope 仓库的管理员与维护者，完整梳理从"发布前测试"到"创建并发布新版本"再到"验证发布结果"的整套运维流程：包括 mock 安装测试脚本的原理、自动化发布脚本publish-and-deploy.sh的七步执行链路、CLI 验证要点，以及网站（gh-pages）部署的底层机制。读完本文，你将能够独立完成一次 speedscope 版本的发布、回滚前的验证与发布后的核验。

文档定位：这份管理员指南覆盖什么

README-ADMINS.md 是仓库中专门面向管理员（admin）的过程文档，与面向普通用户的 README.md 职责不同：后者讲解"如何导入 profile、如何使用视图与快捷键"，前者聚焦"如何安全地把一个新版本发布出去"。

文档首先声明了一个重要前提：发布流程假定在 macOS 上运行。原文明确写到：在 Linux 上"probably works"（可能可用），而在 Windows 上"almost definitely does not work"（几乎肯定不可用）。这意味着管理员在非 macOS 环境执行发布前，应优先在 macOS 机器或等效的 Unix 环境中进行，尤其是下文会提到的npm pack、tar解包、临时目录路径等步骤，与 Unix 工具链强相关。

整个发布流程由一组位于 scripts 目录的 bash 脚本支撑，它们是本文所有命令的底层实现：

第一步：发布前测试（Test the release）

speedscope 的所有自动化测试都由 CI 承担（详见下文"与 CI 的衔接"一节），因此发布前只需要做少量"冒烟检查"（sanity checks），确认构建与发布相关的机器链路本身工作正常。

运行模拟安装脚本

在仓库根目录执行：

scripts/prepare-test-installation.sh

该命令会做一次mock 发布与安装（mock publish & installation），以确认即将发布的版本确实可用。命令结束时，终端会打印一条cd指令，提示切换到测试安装目录，输出形如：

Run the following command to switch into the test directory cd /var/folders/l0/qtd9z14973s2tw81vmzwkyp00000gp/T/speedscope-test-installation.9Ssdd2PZ/package

（具体路径由mktemp动态生成，每次运行都不同。）

脚本背后：mock publish 的完整链路

从 prepare-test-installation.sh 的源码可以看到这个"模拟发布"到底做了什么：

set -euxo pipefail TESTDIR=`mktemp -d -t speedscope-test-installation` # 1. 创建临时目录 PACKEDNAME=`npm pack | tail -n1` # 2. 本地打包生成 .tgz mv "$PACKEDNAME" "$TESTDIR" # 3. 把包移入临时目录 cd "$TESTDIR" tar -xvvf "$PACKEDNAME" # 4. 解包 cd package npm install # 5. 安装依赖 set +x echo echo "Run the following command to switch into the test directory" echo cd "$TESTDIR"/package

关键点在于：脚本用npm pack（本地打包）替代了npm publish（真实发布到 npm registry），再用tar解包、npm install复刻了用户通过npm install -g speedscope会经历的安装过程。这样可以在不污染 npm registry 的前提下，完整验证"打包 → 安装 → 运行"链路。set -euxo pipefail保证任何一步失败都会立即中断，避免带病发布。

该脚本依赖 package.json 中的files字段约定——只有bin/cli.mjs、dist/release/**（排除*.map）会被打进包，这也决定了冒烟测试能验证的范围。

手工冒烟检查步骤

执行上面打印的cd命令进入测试目录后，按文档要求做两项检查：

1. 运行 CLI 并导入本地文件：执行bin/cli.mjs，浏览器会打开一份 speedscope 副本。点击页面上的 browse 按钮，从磁盘导入一个 profile 文件，确认导入功能正常。
2. 测试命令行参数直接加载：执行：

bin/cli.mjs dist/release/perf-vertx*

此时浏览器应立即打开 speedscope，并且 perf-vertx 文件立即加载完成，无需再手动导入。

关于第二个检查项中的dist/release/perf-vertx*通配符：从源码看，speedscope 内置了一份名为perf-vertx-stacks-01-collapsed-all.txt的示例 profile（位于 sample/profiles/stackcollapse/perf-vertx-stacks-01-collapsed-all.txt），并且在应用入口 src/views/application.tsx 中通过loadExample直接fetch该文件作为演示数据。构建产物目录dist/release/中会包含对应的发布版示例文件，因此这条命令既能验证 CLI 的参数加载路径，也能顺带验证示例数据在发布包中是否完整。

CLI 加载机制的源码佐证

CLI 本体是 bin/cli.mjs，它在package.json中被声明为bin入口。当传入文件路径时，它会把文件内容转为 base64，写入一个临时.js文件，再以#localProfilePath=<js 路径>的 hash 参数打开dist/release/index.html：

• 浏览器端在 src/views/application.tsx 中读取hashParams.localProfilePath，加载该临时脚本并调用loadFileFromBase64(filename, base64source)完成导入；
• hash 参数解析逻辑见 src/lib/hash-params.ts，并有对应测试 src/lib/hash-params.test.ts 覆盖#localProfilePath=...的解析。

此外 CLI 还支持以-作为路径参数从 stdin 读取（cat /path/to/profile | speedscope -），以及--help/-h、--version/-v两个标志。由于 macOS 的open与 Windows 的start会忽略 URL 中的 hash 参数，CLI 在darwin/win32平台还会额外生成一个临时 HTML 重定向页来绕开该问题——这也再次印证了"发布流程假定 macOS"的文档前提。

第二步：创建并发布新版本（Create & publish the new release）

发布前置条件

执行发布前，需要确认以下三项就绪：

1. 安装并认证 GitHub CLI：运行gh auth status确认已登录。
2. npm 身份可用：运行npm whoami确认 npm 账号可用。
3. 浏览器登录 npm：在默认浏览器中确保已登录 npm 账号——文档特别提醒，若未登录，在 npm publish 过程中打开 authenticate 链接时会看到 404 页面（该提醒来自 CHANGELOG 中 1.18.0 的 #457 变更，专门为 npm 登录指引补充）。

执行发布脚本

确认就绪后，运行：

scripts/publish-and-deploy.sh

脚本接受一个必填参数，用于指定版本号的提升方式。从 publish-and-deploy.sh 源码看，参数取值可以是minor、patch，或直接指定完整版本号：

Usage: $0 <minor | patch | version> e.g. $0 patch

七步执行链路拆解

从脚本源码（scripts/publish-and-deploy.sh）可以看到，一次发布实际上是如下 7 个环节的串联：

1. 类型检查：node_modules/.bin/tsc --noEmit，与npm run typecheck等价；
2. 单元测试：npm run jest（实际由 test-setup.sh 先解压测试用 zip 样本，再运行 Jest）；
3. 提升版本号但不提交：npm version "$version_arg" --no-git-tag-version --no-commit-hooks，同时更新package.json与package-lock.json，但不立即创建 commit 或 tag；
4. 更新变更日志：调用 print-changelog-update.sh 生成自上一个 tag 以来的提交记录摘要，格式与 CHANGELOG.md 保持一致（## [版本号] - 日期，带 PR 编号与作者署名），并前置写入 CHANGELOG.md；
5. 提交并打标签：git add CHANGELOG.md package.json package-lock.json，以版本号为 commit message，创建v$version形式的 tag，然后git push与git push --tags；
6. 发布到 npm：npm publish；
7. 部署网站 + 构建独立 zip：npm run deploy（对应 deploy.sh），再调用 prepare-zip-file.sh 生成dist/release/speedscope-$version.zip。

收尾：在 GitHub 创建 Release

脚本执行完毕后并不会自动创建 GitHub Release，而是打印出人工操作指引，包括：

• 需要访问的 GitHub Releases 新建页面；
• tag: v$version；
• title: v$version；
• attachment: dist/release/speedscope-$version.zip；
• 以及本次生成的变更日志内容。

脚本源码中注释说明：这一环节"几乎但并非完全"可以用gh release create自动化（脚本里甚至保留了可参考的命令样例），之所以保留人工步骤，是因为两个未解决的问题——--attach标志的退出行为不理想，且不希望 Release 注释包含 CHANGELOG 中的版本号与日期。因此在当前版本中，管理员仍需在网页上手工创建 Release 并上传 zip。

发布时自动执行的构建脚本

第 7 步的 zip 构建依赖 prepare-zip-file.sh：它从 npm registry 拉取刚发布的包（npm pack speedscope），解包后把dist/release/**拷贝进speedscope/目录，附带 LICENSE 与一个说明index.html用途的 README，最后打包为speedscope-<version>.zip放到dist/release/。

发布构建本身由 prepack.sh 完成（对应npm run prepack，使用--protocol file生成可直接双击打开的独立版本；而 deploy.sh 走的是./scripts/prepack.sh --outdir "$OUTDIR" --protocol http，即面向 HTTP 服务的版本）。prepack.sh还会在产物目录写入release.txt（记录 npm 包名、构建日期与git rev-parse HEAD）以及file-format-schema.json（由 generate-file-format-schema-json.js 生成），便于事后定位具体构建对应的 commit。

第三步：验证发布结果（Verifying the release）

验证 npm 包可用

发布完成后，从最终用户视角验证 npm 包：

npm install -g speedscope

随后验证两种调用方式：

1. 无参数启动：直接运行speedscope，浏览器应打开 speedscope 界面；
2. 带参数直接加载 profile：运行

speedscope sample/profiles/stackcollapse/simple.txt

浏览器应立即打开并加载该 profile。仓库中的 sample/profiles/stackcollapse/simple.txt 是标准的 stackcollapse 格式文本（每行一个;分隔的调用栈加权重数值），例如：

a;b;c 1 a;b;c 1 a;b;d 4 a;b;c 3 a;b 5

正是验证 CLI 加载链路的最小样例。此验证与发布前测试中的bin/cli.mjs dist/release/perf-vertx*形成闭环：前者验证源码包，后者验证 npm 安装后的全局命令。

验证网站部署完成

npm 发布成功只代表包可用，网站部署是独立的一条链路。打开 https://www.speedscope.app/ 后，查看浏览器控制台中显示的版本号，确认其与本次发布的版本一致，即表示 gh-pages 部署完成。

网站部署的机制见 deploy.sh：脚本先以--protocol http构建产物到dist/http-release，再对仓库做一次--depth 1的浅克隆（切到gh-pages分支），把构建产物拷贝进去、写入www.speedscope.app的 CNAME 记录，随后在本地http.server 4444启动服务器供人工验证，按Ctrl+C后确认（输入yes）才git push origin HEAD:gh-pages完成部署。这也解释了为什么验证时要以"控制台版本号"为准——部署内容来自本次构建产物。

与 CI 的衔接

发布前的自动化测试保障来自 CI。仓库的 scripts/ci.sh（对应npm test）依次执行：

npm run typecheck npm run lint npm run coverage node scripts/generate-file-format-schema-json.js > /dev/null

即类型检查（tsc --noEmit）、ESLint、带覆盖率统计的 Jest 测试，以及文件格式 schema 的生成校验。其中 jest 配置（package.json）使用 jsdom 环境、ts-jest/esbuild-jest转译，并会把 Java Flight Recorder 的 wasm 模块 mock 掉（jfrview_bg.wasm→ src/import/java-flight-record.mock.ts）。发布脚本内部复用了其中tsc与jest两步，相当于发布前再跑一遍关键检查的双保险。

关键脚本速查

注意事项与常见问题

• 平台限制：整套流程假定 macOS；Linux 可能可用、Windows 几乎不可用。CLI 在 Windows 上需要wait: true打开浏览器（见 bin/cli.mjs），且 macOS/Windows 均需要临时 HTML 重定向来携带 hash 参数，这些平台差异是"假定 macOS"的主要原因之一。
• 版本参数：发布脚本只接受patch、minor或完整版本号三种参数，传入其他值会直接报错退出。
• 顺序不可颠倒：必须先通过发布前测试与手工冒烟检查，再执行发布脚本；npm publish一旦执行即不可撤回，所以冒烟检查中"先验证、后发布"的顺序是流程的核心。
• 变更日志格式：CHANGELOG 条目由脚本自动生成并附带 PR 链接与作者，若 PR 标题包含额外 issue 编号，脚本也会按既定逻辑处理（参见 print-changelog-update.sh 的 sed/grep 处理）。
• 当前仓库版本参考：仓库 package.json 中记录的版本为1.25.0，CHANGELOG.md 最新条目亦为1.25.0（2025-12-03），可作为验证发布流程时对照的基准版本。

• 开发工具
• 前端