Lesson 0009 打包与发布：从代码到 Marketplace

Lesson 0008 让 CI 在每次 push 时自动验证代码。现在流水线还差最后一段：把验证通过的代码变成用户能安装的扩展。本课串联 dev→publish 流水线的后半段——从 .vsix 打包格式到 Marketplace + Open VSX 双平台发布，以及 publish.yml 中 Personal Access Token 的安全设计。

1. 你写的代码怎么变成用户能装的东西

到目前为止，你的代码只存在于 temp_repo/ 目录里——.ts 源文件、package.json、图标、配置文件。用户要安装你的扩展，需要的是一个可分发的包。VS Code 生态里这个包就是 .vsix 文件。

1.1 .vsix 是什么

.vsix（Visual Studio Extension）是一个 ZIP 压缩包，后缀名改了而已。它的内部结构：

claude-context-bar-1.4.1.vsix  ← 文件名 = name + version
├─ extension/               ← VS Code 扩展的根目录
│  ├─ package.json          ← 扩展清单（原样打包）
│  ├─ out/                  ← 编译后的 .js（tsc 产物）
│  │  └─ extension.js
│  ├─ images/               ← 图标、截图等静态资源
│  │  └─ icon.png
│  └─ node_modules/         ← 运行时依赖（如果有）
├─ [Content_Types].xml      ← OPC 标准需要的元数据
└─ extension.vsixmanifest    ← VSIX 包清单（由 vsce 自动生成）

1.2 分发路径：Marketplace 和 Open VSX

claude-context-bar 同时发布到两个平台——这也是 publish.yml 有两个 publish 步骤的原因。对于一个想让尽可能多用户使用的扩展，双平台发布是标准做法。

2. package.json 中的发布字段

不是 package.json 里所有东西都和发布有关。下表列出专门影响 Marketplace 展示和发布流程的字段：

3. vsce package：本地打包

打包工具叫 @vscode/vsce（VS Code Extension 的缩写）。它是 npm 包，通常通过 npx 直接调用而非全局安装：

# 打包——在本地产出 .vsix 文件
npx @vscode/vsce package

# 等价于 package.json 中定义的快捷方式：
# "package": "vsce package"
npm run package

vsce package 的执行流程：

1. 读取 package.json → 验证 name、version、publisher、engines.vscode 都存在
2. 执行 vscode:prepublish 钩子 → npm run compile
3. 收集文件：
   ✅ 包含：package.json、out/、images/、README.md、CHANGELOG.md、LICENSE
   ❌ 排除：src/、node_modules/（devDependencies，除非声明为 dependency）、.git/、*.test.js
4. 生成 extension.vsixmanifest 和 [Content_Types].xml
5. 压缩为 .vsix → 输出文件名 name-version.vsix

4. publish.yml 逐行拆解

回到 temp_repo/.github/workflows/publish.yml——这个 VS Code 扩展模板自带的 workflow：

# ===== .github/workflows/publish.yml =====
name: Publish Extension

on:
  push:
    tags:
      - 'v*'                        ← 推送 v1.0.0 这样的 tag 时触发

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Publish to VS Code Marketplace
        run: npx @vscode/vsce publish -p ${{ secrets.VSCE_PAT }}

      - name: Publish to Open VSX
        run: npx ovsx publish -p ${{ secrets.OVSX_PAT }}

4.1 为什么用 push tag 触发而不是 push branch？

Lesson 0008 的 test.yml 在每次 push 到 main 时触发——这合理：每次改动都要验证。但发布不是每次 push 都该做的事——你不想修个 typo 就发一个新版本。Tag 触发给了你精确控制：只有在刻意打 v1.5.0 tag 时，才触发发布。

完整的发布流程：
1. 开发 → 本地测试通过 → push 到 main
2. CI (test.yml) 通过 ✅
3. 决定发布 → npm version patch → git push origin main --tags
4. CI (publish.yml) 由 tag 触发 → 自动发布到 Marketplace + Open VSX

4.2 Personal Access Token：密钥安全的核心

${{ secrets.VSCE_PAT }} 和 ${{ secrets.OVSX_PAT }} 是 GitHub Actions 的加密密钥机制。关键事实：

1. 密钥不在 workflow 文件里。你在 GitHub 仓库的 Settings → Secrets and variables → Actions 中手动添加。workflow 文件只引用 secrets.XXX——即使有人拿到了仓库源码，也看不到密钥明文
2. 运行时注入环境变量。GitHub Actions 在 job 启动时将 secrets.VSCE_PAT 注入为环境变量。日志中这个值会被自动遮蔽——如果有人试图 echo $VSCE_PAT，输出显示为 ***
3. 最小权限原则。每个 PAT 只授予它需要的权限——VSCE_PAT 只需要 Marketplace 的 publish 权限，OVSX_PAT 只需要 Open VSX 的 publish 权限

5. 版本管理：SemVer 实践

VS Code 扩展使用 Semantic Versioning（语义化版本）：major.minor.patch（如 1.4.1）。每次发布前做三件事：

6. 完整流水线：从编码到发布

把 Lesson 0007、0008 和本课串起来，就是一条完整的 dev→publish 流水线：

编码 (Lesson 0001-0005)
  │  写 extension.ts，注册命令，创建 StatusBarItem
  ↓
本地测试 (Lesson 0007)
  │  npm test → 3 秒确认 8 个 fixture 全部通过
  ↓
CI 验证 (Lesson 0008)
  │  git push → test.yml 在 3 个 Node 版本上并行运行
  │  通过 ✅ → 继续；失败 ❌ → 修 bug
  ↓
发布 (本课)
  │  npm version patch → git push --tags → publish.yml 触发
  │  vsce publish + ovsx publish → Marketplace + Open VSX
  ↓
用户安装
  │  搜索 "Claude Context Bar" → Install → 🎉

7. 练习

1. 在 temp_repo/ 中运行 npx @vscode/vsce package。观察输出：列出了哪些文件？总共多大？有没有包含 src/ 目录？然后解压 .vsix（改后缀为 .zip 然后解压），验证内部结构和第 1 节描述的一致
2. 阅读 temp_repo/CHANGELOG.md（如果不存在就创建一个）。格式参考 keepachangelog.com。思考：CHANGELOG 和 git log 的区别是什么？为什么两者都需要？
3. （思维练习）你修改了一个 typo（文档里多了一个空格）。你应该 bump 哪个版本号——patch、minor 还是 major？如果这个 typo 是功能描述中的，修复后改变了用户对功能的理解呢？
4. 打开 Marketplace 页面，找到 package.json 中 icon、galleryBanner、repository、keywords 分别对应页面上的哪个位置
5. （延伸）在 GitHub 仓库中设置一个假的 PAT（Settings → Secrets → Actions → New repository secret），命名为 VSCE_PAT，值填 test-token-123。这个 token 不会真的能发布，但你会知道密钥是怎么加上去的。然后想想：如果有人 fork 了你的仓库，fork 的 Actions 能读到原仓库的 secrets 吗？（答案：不能——GitHub 不传递 secrets 到 fork）
6. （延伸）修改 publish.yml，在 publish 步骤之前增加一个 npm test 步骤。再想想：这个改动有什么问题？回顾 Lesson 0008 第 4 节的 callout——两个独立 workflow 之间没有依赖。更好的做法是什么？（提示：needs 关键字，或者把 test 和 publish 合并成一个 workflow）

8. 知识检查

9. 推荐深入阅读

• VS Code：Publishing Extensions — 官方发布文档，含 publisher 注册、PAT 创建、vsce 完整用法
• microsoft/vscode-vsce — vsce 源码仓库。了解 .vsixmanifest 如何生成、排除规则如何配置（.vscodeignore）
• Open VSX Registry — 社区维护的 VS Code 扩展注册表。理解为什么需要双平台发布
• 语义化版本 2.0.0 — SemVer 规范的官方中文翻译。1-2-3 规则的全部细节
• Keep a Changelog — CHANGELOG 的书写规范。和 SemVer 配套使用的最佳实践
• GitHub Actions：Using secrets — 密钥加密、日志遮蔽、fork 限制的完整文档
• GitHub Actions：jobs.<job_id>.needs — 让 publish job 依赖 test job 通过（Lesson 0008 第 4 节提出的改进方向）
• Lesson 0008：CI 集成 — 本课的直接前置：CI 验证代码 → 发布可验证的代码