Gemini CLI 扩展有两种发布方式：Git 仓库（简单灵活，适合大多数扩展）和 GitHub Releases（预构建包，适合含原生二进制的扩展）。发布后，只需给仓库添加 gemini-cli-extension 话题，扩展库会在次日自动收录。本页还介绍如何用 migratedTo 字段无痛迁移扩展仓库。

发布 Gemini CLI 扩展

Gemini CLI 扩展可通过两种方式发布：Git 仓库（最灵活）和 GitHub Releases（适合需要预构建或平台特定二进制文件的场景）。

---

收录到扩展库

Gemini CLI 扩展库 自动索引公开扩展，无需提交 Issue 或发邮件。

收录条件：

1. 使用公开 GitHub 仓库
2. 在仓库 About 部分添加 gemini-cli-extension 话题（这是爬虫的发现依据）
3. manifest 文件在仓库根目录：gemini-extension.json 必须位于绝对根路径

爬虫每天运行一次，验证通过后自动出现在扩展库中。

---

方式一：Git 仓库发布

最灵活的发布方式，适合大多数扩展。

用户安装命令：

gemini extensions install <your-repo-url>

• 每次向对应分支推送 commit，CLI 会提示用户更新
• HEAD commit 始终视为最新版本
• 用户可用 --ref 指定分支、tag 或 commit：

gemini extensions install <your-repo-url> --ref=stable

管理发布渠道

用 Git 分支管理稳定版和开发版：

# 用户安装稳定版（默认分支）
gemini extensions install github.com/user/repo

# 用户安装开发版
gemini extensions install github.com/user/repo --ref dev

推荐策略：

• 默认分支（main/master）= 稳定发布渠道，始终保持可用
• dev 分支 = 活跃开发，功能成熟后合并到默认分支
• 可选：preview 分支提供介于两者之间的抢先体验版

---

方式二：GitHub Releases

通过 GitHub Releases 分发，安装更快（无需完整 git clone，直接下载压缩包）。

适用场景：

• 扩展需要编译步骤（TypeScript → JavaScript）
• 包含平台特定二进制文件

用户可用 --pre-release 安装最新 pre-release 版本：

gemini extensions install <your-repo-url> --pre-release

平台特定包命名规范

如果需要为不同平台提供不同包，使用以下命名约定：

格式	示例
{platform}.{arch}.{name}.{ext}	darwin.arm64.my-tool.tar.gz
{platform}.{name}.{ext}	darwin.my-tool.tar.gz
{name}.{ext}（通用后备）	my-tool.tar.gz

占位符取值：

• {platform}：darwin（macOS）、linux、win32（Windows）
• {arch}：x64、arm64
• {ext}：.tar.gz（Unix/macOS）、.zip（Windows）

CLI 按 "平台+架构特定 → 平台特定 → 通用" 顺序匹配，找到第一个匹配项下载。

压缩包结构

压缩包必须完整自包含，gemini-extension.json 必须在压缩包根目录。

GitHub Actions 自动打包示例

name: Release Extension

on:
  push:
    tags:
      - 'v*'

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Build extension
        run: npm run build

      - name: Create release assets
        run: |
          npm run package -- --platform=darwin --arch=arm64
          npm run package -- --platform=linux --arch=x64
          npm run package -- --platform=win32 --arch=x64

      - name: Create GitHub Release
        uses: softprops/action-gh-release@v1
        with:
          files: |
            release/darwin.arm64.my-tool.tar.gz
            release/linux.x64.my-tool.tar.gz
            release/win32.x64.my-tool.zip

---

迁移扩展仓库

如果需要将扩展迁移到新仓库（如从个人账号迁到组织），使用 migratedTo 字段实现无痛用户迁移：

步骤：

1. 建立新仓库，在新位置设置好扩展

2. 更新旧仓库 gemini-extension.json，添加 migratedTo 并提升版本号：

   {
     "name": "my-extension",
     "version": "1.1.0",
     "migratedTo": "https://github.com/new-owner/new-extension-repo"
   }

3. 在旧仓库发布新版本

当用户检查更新时：

• CLI 检测到 migratedTo 字段
• 验证新仓库包含有效的扩展更新
• 自动将用户的安装源更新到新仓库
• 所有 Extension Settings 自动迁移到新安装位置

用户无需手动卸载和重新安装。

---

常见问题

Q: 发布到 GitHub 后多久能在扩展库中看到？

A: 爬虫每天运行一次，通常 24 小时内会出现。确保仓库已添加 gemini-cli-extension 话题，且 gemini-extension.json 在根目录。

Q: 发布 Git 版本和 GitHub Releases 版本，用户需要区别对待吗？

A: 安装命令相同（都是 gemini extensions install <url>），CLI 会自动判断使用哪种方式。如果检测到 GitHub Releases，优先下载压缩包；否则 git clone。

Q: 可以同时提供 Git 发布和 GitHub Releases 吗？

A: 可以。CLI 会优先使用 GitHub Releases（如果存在 Latest Release），回退到 git clone。你可以两种方式同时维护，它们不冲突。