GraphiQL 仓库发布流程解析从 Changesets 到 VSCode 扩展双市场自动发布【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql本指南围绕仓库根目录的 RELEASING.md 展开详解 GraphiQL 单仓库monorepo的版本发布机制重点剖析 VSCode 扩展自动化发布流水线scripts/release-vscode.mts的四个命令build、attach、publish-vsce、publish-ovsx及其背后的设计取舍。读完本文你将掌握该仓库从 Changesets 版本管理到 VSCode Marketplace / Open VSX 双市场发布、再到 GitHub Release 制品回传的完整链路并能复现本地调试发布脚本的方法。一、发布体系总览Changesets 驱动的双轨制GraphiQL 仓库是一个包含 npm 包与 VSCode 扩展两类发布产物的单仓库。RELEASING.md 明确指出其发布主流程已交由Changesets驱动文档中标注了 TODO: Redo for changesets指向自动生成的 .changeset/README.md该文件由changesets/cli生成说明 changesets 已深度集成。在根目录 package.json 中可以看到 changesets 的接入点scripts: { ci:version: yarn changeset version yarn install --no-immutable yarn build yarn fix, release: yarn build yarn build-bundles yarn changeset publish }ci:version在版本 PR 合并时执行先由changeset version根据各包的 changeset 文件提升版本号并更新 CHANGELOG随后重装依赖、全量构建并执行格式化修复release在发布阶段执行先构建全部包与 VSCode 扩展 bundlebuild-bundles再由changeset publish将 npm 包发布到 npm registry。双轨制中的第二轨道VSCode 扩展与 npm 包轨道不同三个 VSCode 扩展vscode-graphql、vscode-graphql-syntax、vscode-graphql-execution并不通过changeset publish直接上架而是由发布工作流在 npm 发布完成后将扩展发布管线交接给专门的 TS 脚本 scripts/release-vscode.mts。这一交接逻辑在 .github/workflows/release.yml 中有清晰体现见下文第四节。二、release-vscode.mts四个命令的完整拆解scripts/release-vscode.mts 是整条扩展发布流水线的核心通过node scripts/release-vscode.mts command调用支持四个子命令。脚本顶部定义了受管扩展清单const PACKAGES [ vscode-graphql, vscode-graphql-syntax, vscode-graphql-execution, ] as const;三个扩展的用途与版本信息可分别在 packages/vscode-graphql/package.json、packages/vscode-graphql-execution/package.json、packages/vscode-graphql-syntax/package.json 中确认包名显示名职责vscode-graphqlGraphQL: Language Feature Support基于 LSP 的补全、校验、跳转定义、悬停、大纲等语言能力vscode-graphql-syntaxGraphQL: Syntax Highlighting语法高亮覆盖 JS/TS/Vue/Markdown/Python/PHP/Scala/Reason 等嵌入式场景vscode-graphql-executionGraphQL: Inline Operation Execution在代码内联执行 GraphQL 操作命令一build —— 打.vsix安装包async function build(packages: VscodePackage[]): Promisevoid { await runForEach(packages, build, async pkg { const { status } spawnSync(yarn, [workspace, pkg, vsce:package], { stdio: inherit, }); // ... }); }build通过yarn workspace pkg vsce:package为每个扩展调用其自身的打包脚本。例如 packages/vscode-graphql/package.json 中定义vsce:package: vsce package --yarn --no-dependencies--no-dependencies表示不将依赖打包进扩展扩展运行期依赖由graphql-language-service-server、vscode-languageclient等提供产物.vsix输出到packages/pkg/pkg-version.vsix路径由脚本中的vsixPath工具函数按baseDir/packages/${pkg}/${pkg}-${version}.vsix拼出。命令二attach —— 把.vsix挂到 GitHub Releaseasync function attach(packages: VscodePackage[]): Promisevoid { await runForEach(packages, attach, async pkg { const version await readVersion(pkg); const tag ${pkg}${version}; const path vsixPath(., pkg, version); const { status } spawnSync( gh, [release, upload, tag, path, --clobber], { stdio: inherit }, ); // ... }); }attach为每个已发布扩展执行gh release upload tag vsix --clobber其中tag 遵循${pkg}${version}格式如vscode-graphql0.13.5版本号实时从各扩展的package.json读取--clobber允许同名资产覆盖保证重跑流水线时幂等该命令依赖GH_TOKEN环境变量提供 GitHub API 权限。命令三publish-vsce —— 上架 VSCode Marketplaceasync function publishToVsce(packages: VscodePackage[]): Promisevoid { const pat requireEnv(VSCE_PAT); await runForEach(packages, vsce publish, async pkg { await publishVSIX(path, { pat, skipDuplicate: true }); }); }该命令调用vscode/vsce的publishVSIX将制品发布到官方 VSCode Marketplace需要VSCE_PAT环境变量Marketplace 的 Personal Access Token并开启skipDuplicate: true以跳过重复版本。命令四publish-ovsx —— 上架 Open VSX Registryasync function publishToOvsx(packages: VscodePackage[]): Promisevoid { const pat requireEnv(OVSX_PAT); await runForEach(packages, ovsx publish, async pkg { const results await ovsxPublish({ extensionFile: path, pat, skipDuplicate: true }); const rejected results.filter(r r.status rejected); if (rejected.length 0) { throw new AggregateError(rejected.map(r r.reason), ${rejected.length} target(s) rejected by Open VSX); } }); }publish-ovsx使用ovsx包发布到 Open VSX RegistryVSCode 的开放替代市场需要OVSX_PAT。与 vsce 命令略有差异ovsxPublish返回按目标拆分的 Promise 结果数组脚本会过滤出rejected状态并以AggregateError聚合抛出便于定位具体是哪个目标被拒绝。三、关键设计为什么把.vsix附加到 GitHub Releases原文档明确给出了三个理由均在真实发布场景中成立registry 降级时可直连下载当 VSCode Marketplace 或 Open VSX 不可用时用户可以从 GitHub Release 直接下载与官方渠道完全一致的.vsix手工安装PAT 过期后的人工补救Marketplace / Open VSX 的 token 过期会导致自动上架失败此时仍可从 GitHub Release 拿到制品手动重新上传需要确切的发布位GitHub Release 上留存的是与发布流程完全同源的产物便于审计与回溯无需再经过市场渠道。这一策略的收益在于把渠道发布可能因外部凭据失败与产物留存GitHub Release 始终可写解耦保证每次发版都留下可下载的制品快照。四、为什么用 TS 脚本而不是 Workflow Shell原文档指出逐包迭代per-package iteration、版本查找version lookups和 registry-API 调用放在类型检查的 TS 文件中比散布在release.yml的run:bash 块中更整洁也更安全。对应源码可以佐证三点可类型检查脚本在 scripts/tsconfig.json 的约束下编译该配置开启strict、noImplicitAny、noUnusedLocals、noFallthroughCasesInSwitch等严格检查根目录 package.json 的types:check脚本也会执行tsgo --noEmit -p scripts/tsconfig.json把发布脚本纳入 CI 静态检查范围可本地 mock 复现脚本通过publishedVscodePackages()读取PUBLISHED_PACKAGES环境变量JSON 数组形如[{name:vscode-graphql,version:0.13.5}]本地只需设置该变量即可模拟本次发布了哪些扩展无需真正触发 changesets 发布PUBLISHED_PACKAGES[{name:vscode-graphql,version:0.13.5}] \ node scripts/release-vscode.mts build若变量缺失或为空脚本会打印No VSCode extensions were published; nothing to do.并以状态码 0 退出——这是工作流中过滤仅本次实际发布的扩展的关键机制publishedVscodePackages()从 changesets 输出的publishedPackages中筛出命中的 VSCode 包名未命中则跳过对应操作失败聚合而非短路runForEach会逐个尝试所有包收集每个包的失败并统计总数最后抛出${failures}/${packages.length} ${label} operation(s) failed。这与 bashset -e的第一个错误立即退出不同避免了一个扩展失败导致其余扩展全部未发布的情况。五、工作流编排release.yml 中的完整发布链路发布工作流定义在 .github/workflows/release.yml可概括为两个 Job 的接力Job 1release版本与制品触发条件为main或release/*分支的 push并配置concurrency组防止并发发布cancel-in-progress: false注释强调不要在发布中途取消使用changesets/actionv1传入version: yarn ci:version与publish: yarn release产出publishedPackages本次实际发布的包清单输出步骤Note VSCode extension release通过contains(publishedPackages, name:vscode-graphql)判断本次是否发布了任一 VSCode 扩展并输出published标记随后依次执行node scripts/release-vscode.mts build与node scripts/release-vscode.mts attach两者都注入PUBLISHED_PACKAGES环境变量attach 额外注入GH_TOKEN最后用actions/upload-artifactv4将packages/vscode-graphql*/*.vsix上传为vscode-extensions制品供下一个 Job 消费。Job 2publish-vscode-extensions市场发布通过needs: release依赖前一 Job并仅在vscode-published true时执行使用 matrix 并行发布到两个市场VSCode Marketplace命令publish-vsce与Open VSX Registry命令publish-ovsx且fail-fast: false保证一个市场失败不影响另一个用actions/download-artifactv4恢复制品。注释特别说明upload-artifact会剥离路径前缀制品内是vscode-graphql*/*.vsix而非packages/vscode-graphql*/*.vsix因此下载时指定path: vsix/packages还原packages/前缀恰好与脚本中publishToVsce/publishToOvsx使用的vsixPath(vsix, pkg, version)布局对齐发布步骤注入VSCE_PAT与OVSX_PAT两个密钥OVSX_PAT来自secrets.OPEN_VSX_TOKEN再执行node scripts/release-vscode.mts ${{ matrix.command }}。发布前的质量门禁值得一提的是 scripts/prepublish.sh它显式拒绝在非 CI 环境CI ! true发布 npm 包并要求发布前依次通过yarn lint yarn build yarn build-bundles yarn test yarn e2e从流程上保证进入市场的产物已通过完整质量检查。六、本地调试与复现建议基于上述源码结构可以在本地安全地演练整条流水线仅打包不发布设置 mock 的PUBLISHED_PACKAGES后运行node scripts/release-vscode.mts build观察.vsix是否生成于packages/pkg/下验证发布脚本本身在仓库根目录执行yarn types:check其中包含对 scripts/tsconfig.json 覆盖的scripts/*.mts的类型检查走一遍打包命令yarn workspace vscode-graphql vsce:package可单独验证单个扩展的打包链路完整发布流程只应在 CI 中触发npm 包一侧由 scripts/prepublish.sh 强制 CI 环境扩展发布则依赖 GitHub Actions 的 secretsGH_TOKEN、VSCE_PAT、OPEN_VSX_TOKEN本地不建议也无权直接执行publish-vsce/publish-ovsx/attach。七、小结GraphiQL 仓库的发布体系以 Changesets 为主版本驱动npm 包与 VSCode 扩展两条轨道分工明确npm 包由changeset publish直接发布VSCode 扩展则由 scripts/release-vscode.mts 承接——build打包、attach回传 GitHub Release、publish-vsce与publish-ovsx双市场上架配合 .github/workflows/release.yml 的 Job 接力与 matrix 并行、以及PUBLISHED_PACKAGES驱动的仅发布本次实际变更的扩展过滤机制形成了一套失败可聚合、可本地复现、产物可追溯的自动化发布闭环。对维护多 VSCode 扩展单仓库的团队而言这套TS 脚本 环境变量注入 artifact 传递 双市场矩阵的组合是值得参考的工程范本。【免费下载链接】graphiqlGraphiQL the GraphQL LSP Reference Ecosystem for building browser IDE tools.项目地址: https://gitcode.com/GitHub_Trending/gr/graphiql创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考