GitHub Gist 使用说明：把一段代码变成一条可版本化的链接

Gist 大概是 GitHub 上被误解最深的功能：多数人以为它只是「能贴代码的网页」，实际上它是一个有提交历史、能被 git clone、能被嵌入、能调 REST API 的迷你仓库。
这篇把它一次讲清：怎么建、怎么管、怎么用，以及哪些事绝对不能用它做。

一、先纠正三个误解

在讲操作之前，先把最容易出事的认知摆正。

记住这三条，后面的内容基本就是在它们上面长出来的。

二、Gist 到底是什么

一句话：Gist 是一个没有目录、默认轻量、但完整具备 Git 能力的仓库。

它具备：

• 提交历史：每次编辑都是一个 revision，可以看 diff、可以回到任意一版；
• git 协议：可以 git clone、改完 git push；
• 协作原语：star、fork、评论；
• REST API：可以脚本化创建、更新、删除；
• 三种链接：给人看的网页、给程序读的 raw、给 git 用的仓库地址。

它不具备：目录结构、Issue、Pull Request、Actions、GitHub Pages、私有可见性、二进制文件。这七条缺失决定了它的适用边界（第八节逐条展开）。

三、三种创建方式

3.1 网页：一次性的、要立刻发出去的东西

打开 https://gist.github.com，填三样东西就完事：

• Filename including extension：这一步不能省。扩展名决定了语法高亮，也决定了渲染方式——.md 会渲染成排版好的文档，.json/.yaml/.sh 会按语言高亮，不写扩展名就是纯文本。
• Gist description：会显示在列表和卡片上，建议写清「这是什么、给谁看」。
• 正文：直接粘贴。

右下角两个按钮，就是全部可见性选项：

• Create public gist：会出现在 Discover（gist.github.com/discover）、可被搜索、可被别人 fork；
• Create secret gist：不出现在 Discover、不出现在搜索、不出现在你的公开 gist 列表（未登录访问你的主页看不到）。

3.2 GitHub CLI：日常最省事的方式

安装（各平台一条命令）：

# Windows
winget install --id GitHub.cli

# macOS
brew install gh

# RHEL / Fedora
sudo dnf install gh

# Debian / Ubuntu（官方源）
sudo apt install gh

登录一次，之后所有操作免交互：

gh auth login

常用操作：

# 从文件创建（默认 secret，加 -p 才是 public）
gh gist create notes.md --desc "某接口排查笔记"

# 指定文件名、显式公开
gh gist create -f setup.sh -p ./install.sh

# 从标准输入创建：管道里的东西直接变成 gist
echo "hello" | gh gist create -
kubectl logs deploy/api | gh gist create -f api.log

# 列出、查看、取原始内容
gh gist list -L 20
gh gist view <id> --raw
gh gist view <id> --filename a.txt

# 改：加文件、删文件、改描述
gh gist edit <id> --add new.txt
gh gist edit <id> --remove old.txt
gh gist edit <id> --desc "新描述"

# 当仓库用
gh gist clone <id>

# 删（会二次确认）
gh gist delete <id>

3.3 REST API：放进脚本、放进流水线

创建（"public": false 即 secret）：

curl -sS -X POST https://api.github.com/gists \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  -d '{
    "description": "构建产物摘要",
    "public": false,
    "files": {
      "summary.md": { "content": "# 本次构建\n\n全部通过。" }
    }
  }'

更新、读取、删除：

# 更新某个文件的内容（生成新 revision）
curl -sS -X PATCH https://api.github.com/gists/<id> \
  -H "Authorization: Bearer $GITHUB_TOKEN" \
  -d '{"files":{"summary.md":{"content":"# 本次构建\n\n2 个用例失败。"}}}'

# 读取（注意：文件大于 1MB 时 content 会被截断，需改用 raw_url）
curl -sS https://api.github.com/gists/<id> \
  -H "Authorization: Bearer $GITHUB_TOKEN"

# 删除
curl -sS -X DELETE https://api.github.com/gists/<id> \
  -H "Authorization: Bearer $GITHUB_TOKEN"

四、public 与 secret：必须记住的一条边界

最后两行是重点。secret gist 的 ID 是 32 位十六进制——猜不到，但一旦链接出现在任何公开的地方（聊天记录、论坛、issue、截图、浏览器 referer、第三方抓取服务），它就和 public 没有区别了，而且会被搜索引擎收录。

另外两点：

• secret 可以随手改成 public（编辑页有入口），一次误点就等于公开发布，且可能已被抓取；
• public 改回 secret 没有稳定入口，请视为单向操作（以官方界面为准）。

五、文件、修订与 git 用法

5.1 多文件，但没有目录

一个 Gist 里可以有任意多个文件，文件平铺在同一层，文件名必须唯一。文件名写成 docs/readme.md 也不会生成子目录——它只是名字里带了个斜杠，在 URL 里还会被转义。这是 Gist 最硬的限制：只要你想表达「目录」，就该换仓库。

5.2 每一次编辑都是一个可寻址的版本

• https://gist.github.com/<user>/<id>：看最新版；
• https://gist.github.com/<user>/<id>/revisions：看全部历史，逐版 diff；
• https://gist.github.com/<user>/<id>/<sha>：固定到某一版——这个链接永远指向当时的内容，是「可复现」的关键。

5.3 当成 git 仓库用

# 克隆（三种写法都能用）
git clone https://gist.github.com/<id>.git
git clone https://gist.github.com/<user>/<id>.git
git clone git@gist.github.com:<id>.git

# 之后就是普通的 git 流程
cd <id>
vim something.md
git add -A && git commit -m "补一段说明"
git push

几个容易忽略的点：

• push 是新增提交，不是覆盖——历史永远在，写错了也能翻回来；
• 推送需要凭据：HTTPS 用 PAT（密码方式已不可用于 git 操作），SSH 用已登记的密钥；
• 克隆下来的目录名就是 gist ID，可以自己改名；
• 多个文件改动在一次提交里推上去，只算一个 revision，比在网页上逐个文件点改要干净得多。

六、引用与嵌入

6.1 raw 链接：给程序读

# 永远指向最新版
https://gist.githubusercontent.com/<user>/<id>/raw/<filename>

# 固定到某一版（推荐脚本里用这个）
https://gist.githubusercontent.com/<user>/<id>/raw/<sha>/<filename>

脚本、CI、Dockerfile 里引用外部内容，一律固定到 sha。用「最新版」的写法，意味着别人随时可以改掉你依赖的东西——今天跑通、明天失败的经典来源。

6.2 嵌入网页

<script src="https://gist.github.com/<user>/<id>.js"></script>

<!-- 只嵌入其中某个文件 -->
<script src="https://gist.github.com/<user>/<id>.js?file=notes.md"></script>

<!-- 锁定到某一版 -->
<script src="https://gist.github.com/<user>/<id>/<sha>.js"></script>

嵌入失败时，按这个顺序查：

1. 页面的 CSP 是否放行 gist.github.com（我们自己的站点就设了严格的 script-src，默认情况下会被浏览器直接拦掉——这属于正常的安全策略，不是 Gist 坏了）；
2. 页面是否禁用了 JS，或用了纯静态渲染；
3. 网络能否访问 gist.github.com（内网、代理、地区网络都可能是原因）；
4. secret gist 不要指望能嵌入——官方不提供这个能力，要嵌入就建 public。

七、九个真实场景

下面每一条都能直接抄。

1. 贴一段报错或日志

journalctl -u myservice --since "1 hour ago" | tail -n 300 \
  | gh gist create -f myservice.log --desc "服务重启前的 300 行日志"

贴之前先脱敏：把 IP、域名、账号、token、内部主机名替换掉。日志是最容易顺手泄露基础设施信息的东西。

2. 分享一段配置

nginx / systemd / docker-compose 之类，用 -f 指定真实文件名，看的人一眼就知道该放哪。

3. 分享一次性脚本

gh gist create -p -f fix-dns.sh ./fix-dns.sh

4. 一份短文档

文件名用 .md，会直接渲染成排版好的页面（标题、列表、表格、代码块都支持）。比新建仓库轻，比发聊天记录可读。

5. 临时的「改动前 / 改动后」对比

把旧版本先建成一个 gist，改完再建一个，然后用 gist 的 revisions 页面看 diff；或者直接把两份文件放进同一个 gist 的两个文件里，谁改了什么一目了然。

6. 给同事或 AI 的上下文包

一个 README.md 写清目标与约束，加两三个样例文件（输入样本、期望输出、错误日志），链接发出去即可。这比在聊天窗口里贴十几段代码有效得多——对方拿到的是有结构、可引用的材料。

7. 轻量的配置分发

curl -sSL https://gist.githubusercontent.com/<user>/<id>/raw/<sha>/agent.yaml \
  -o /etc/myapp/agent.yaml

8. 嵌进博客或文档站

见 6.2。适合「示例代码需要长期维护、但不想复制粘贴到文章里」的场景。

9. 当一个小 JSON 数据源

curl -sS https://api.github.com/gists/<id> \
  | jq -r '.files["data.json"].content'

能做，但要克制：没有并发控制、没有事务、公开可读、有 CDN 缓存、有 API 限流。它适合「人工偶尔改一次的小配置」，不适合当数据库。

八、十一个一定会踩的坑

九、安全清单

发布前自查（贴在习惯里，比事后补救便宜一万倍）：

grep -nEi '(api[_-]?key|secret|token|passw(or)?d|BEGIN [A-Z ]*PRIVATE KEY|ghp_|github_pat_|sk-)' 待发布文件

万一已经发出去了，按这个顺序处理：

1. 先吊销——token 撤销、密钥轮换、口令改掉；
2. 再删除或修改 Gist 内容；
3. 查使用记录（API 日志、登录记录、云厂商审计），确认有没有被用过；
4. 通知相关方，评估影响面。

另外两条原则：

• secret gist 也按公开对待——这是唯一安全的默认假设；
• 团队内部共享走私有仓库，不要用 secret gist 当「内部资料区」。

十、速查表

十一、结语：一条判断标准

Gist 的定位很清楚：临时的、单层的、要被立刻看到的、需要一点点版本能力的东西。它把「贴一段代码」这件事的成本压到了最低，同时保留了 Git 的可追溯性——这就是它十几年没过时的原因。

反过来，凡是需要目录、二进制、权限、多人协作、长期维护的，它都不合适，勉强用只会把问题推迟到更贵的时候爆发。

所以我们自己的判断标准只有一句话：

如果你会为它写第二个 README，它就不该是 Gist。

工具的价值不在于能做多少事，而在于知道它在哪一刻该停。Gist 是这样，我们做系统时对待每一个「临时方案」也是这样。