---
url: https://eoht.net/notes/build-picture-bed.md
description: >-
  使用 GitHub 公共仓库搭配 PicGo 或 PicList 上传图片，说明两种客户端的 Token 配置依据、仓库与分支字段、上传验证、403/404
  排查及令牌更换。
---

# PicGo/PicList + GitHub 搭建图床 {#github-image-hosting-with-picgo}

这里用专门的 GitHub 公共仓库存放公开文章图片。客户端负责把文件写入仓库，再返回图片 URL；上传完成后还要确认读者可以匿名访问该 URL。

## 准备工作 {#prerequisites}

<Links
:grid="3"
:items="[
 {
   icon: { icon: 'cib:github', color: { light: '#000', dark: '#fff' } },
   name: '注册 GitHub 账号',
   desc: '上传图片前需先拥有一个 GitHub 仓库',
   link: 'https://github.com/'
 },
 {
   image: 'https://molunerfinn.com/PicGo/imgs/256x256--icons.png',
   name: 'PicGo',
   desc: '用于快速上传图片并获取图片 URL 链接的工具',
   link: 'https://molunerfinn.com/PicGo/'
 },
 {
   image: 'https://pichoro.msq.pub/favicon/app_icon.png',
   name: 'PicList',
   desc: '高效的云存储和图床平台管理工具，基于 PicGo 深度二次开发',
   link: 'https://piclist.cn/'
 }
]"
/>

## 创建新仓库 {#create-github-repository}

新建一个专门的图片仓库，例如 `docs-images`，选择 Public 并初始化 README，使目标分支实际存在。记下完整的 `owner/docs-images` 和分支名；`owner` 代表你的用户名或组织名，不能原样照抄。分支可能是 `main`、`master` 或自定义名称，按仓库实际值填写。

公共仓库中的图片和历史内容都可以被他人读取，不要将私人截图或配置备份作为图床素材。

![PicGo =688x](https://i.eoht.net/docs/20230902143628.webp "仓库必须是 `public` 的，否则存储的图片不能正常访问。")

## 生成 Token {#generate-access-token}

Token 类型与权限应按所用客户端核对，不能把旧截图中的 `repo` 勾选视为所有客户端的最低权限：

| 客户端 | 当前维护方依据 | 本文采用的配置 |
| --- | --- | --- |
| PicList | [GitHub 图床文档](https://piclist.cn/providers/github) 明确给出 fine-grained Token | 仅选择图床仓库，授予 `Contents: Read and write` |
| PicGo | [官方配置手册](https://picgo.github.io/PicGo-Doc/zh/guide/config.html#github图床) 的示例仍使用 classic Token 与 `repo` | 按官方示例配置，但先理解下述较大的授权范围 |

**PicList 的 fine-grained Token**：进入 GitHub「Settings」→「Developer settings」→「Personal access tokens」→「Fine-grained tokens」，选择正确的 Resource owner，在仓库范围中仅选图床仓库，并设置 Contents 读写权限与有效期。组织仓库可能需要批准。普通图片上传不需要 Workflows 写权限，依据是 [GitHub 仓库内容 API](https://docs.github.com/en/rest/repos/contents#create-or-update-file-contents)。

**PicGo 的 classic Token 示例**：打开 <Pill icon="oui:token-key" name="GitHub Token 设置" link="https://github.com/settings/tokens" />，选择 `Tokens (classic)` → `Generate new token (classic)`，填写用途和有效期，再按官方示例授权。`repo` 涵盖账户有权访问的公共及私有仓库，并非仅限当前图床。GitHub 另有范围较小的 `public_repo`，限公共仓库，但仍不是单仓库授权；使用它前应核对实际客户端所需操作并测试。权限定义见 [GitHub scope 说明](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps)。

PicGo 上传器使用仓库内容 API，但本文没有对所有已发布客户端版本执行 fine-grained Token 测试，因此不把 API 支持直接写成所有 PicGo 版本均已验证支持。

![PicGo =688x](https://i.eoht.net/docs/20230902144325.webp "旧版 classic Token 授权界面；repo 的授权范围包括公共和私有仓库")

:::tip 注意
**Token 生成后只显示一次。** 保存到私人密码管理器，只填入客户端的 Token 字段，不放进图片 URL、截图或公开的配置文件。
:::

## 配置 PicGo 或 PicList {#configure-picgo}

进入客户端的 GitHub 图床设置，创建或编辑一套上传配置。两种客户端的界面名称略有差异，字段含义如下：

| 字段 | 示例 | 说明 |
| --- | --- | --- |
| 图床配置名 | `文章图片` | 客户端内用于辨认的名字 |
| 仓库名 / `repo` | `owner/docs-images` | 用户或组织名加仓库名，不填完整网页 URL 或 `.git` 后缀 |
| 分支 / `branch` | `main` | 必须是该仓库实际存在的目标分支 |
| Token / `token` | 在本机填写 | 使用上一步创建的令牌 |
| 存储路径 / `path` | `img/` | 仓库内目录，以 `/` 结尾；留空表示仓库根目录 |
| 自定义域名 / `customUrl` | 首次测试留空 | 有已经可用的资源域名后再设置 |

保存配置，选中它，并将 GitHub 设为默认图床。PicList 的上传配置与云端管理配置是不同入口；本节配置的是上传。

![PicGo =688x](https://i.eoht.net/docs/20230902150820.webp "配置 PicGo")

## 上传与结果检查 {#verify-github-image-upload}

1. 上传一个名称未被使用的小图片，例如 `upload-test-20261024.png`。
2. 在 GitHub 的目标分支和 `img/` 目录确认文件存在，打开检查是否为刚上传的图片。
3. 从客户端复制图片 URL，在未登录 GitHub 的浏览器窗口打开，再粘贴到文章预览检查。

默认直链通常形如 `https://raw.githubusercontent.com/owner/docs-images/main/img/upload-test-20261024.png`。这是字段示例，需换成自己的值；不要使用带 `blob` 的 GitHub 文件网页地址作为图片地址。首次上传验证完成后，再配置自定义域名或其他链接改写。

同名文件不应被视为已经覆盖成功。使用新文件名，或通过明确的仓库文件更新流程替换，再检查实际内容；某些客户端可能返回已有路径，而文章仍显示旧图。

## 失败排查与 Token 更换 {#github-upload-errors-and-token-rotation}

| 现象 | 检查 |
| --- | --- |
| `401` | Token 是否完整、过期或已撤销 |
| `403` | 写权限、仓库授权范围、组织批准或 SSO、分支规则，以及日志中的 API 限流说明 |
| `404` | `owner/repo` 拼写、仓库与分支是否存在；授权不足时也可能返回 404 |
| `409` / `422` 或同名冲突 | 仓库是否初始化、分支是否正确、同一路径是否已有文件；换一个新文件名测试 |
| 上传成功但图片打不开 | 是否为公开可读的图片直链，是否误用了网页 URL，自定义域名与目录是否拼接正确 |
| 图片仍是旧内容 | 先看仓库文件，再核对引用 URL 和浏览器/CDN 缓存 |

查看客户端日志时保留状态码和错误描述，分享前去掉 Token。定期更换令牌时，先创建新 Token，在每个使用它的客户端中替换并保存，上传一张测试图确认成功后，再撤销旧 Token；如果旧令牌已泄露，则先撤销，再配置新令牌。更换 Token 通常不改变已有公开图片地址。