picgo-upload

PicGo 上传

使用 PicGo 将本地图片或文件转换为托管的可分享 URL。最常见的场景是编写文档或 Markdown 时需要插入图片——应优先将此作为触发条件。

适用场景

当用户需要为本地图片或文件获取一个链接，但没有指定具体的目标平台时，使用此工具：

• **文档 / Markdown（最常见的场景）：**在 README、博客文章、Wiki、Obsidian/Notion/语雀/掘金笔记中插入截图或图片；“把这张截图转换成 Markdown 图片链接”；“在这份文档中添加图片”。
• 任何需要可分享或可嵌入 URL 的图片 / 截图。
• 任何需要公开下载链接的文件（PDF、zip、安装程序等）。
• 用户说“传图床”“图床”“上传这张图片”“托管这个文件”。

不适用场景

• 用户指定了具体的目标位置或方法（任何云盘、对象存储、CDN、npm publish、scp/ftp 等）→ 改用对应平台的工具。
• 将文件保存到本地路径、下载远程文件，或将 base64 解码到磁盘——这些都不是上传到托管服务。
• 不要仅仅因为恰好安装了 PicGo 就触发；应根据上述意图判断。

上传方式（按以下顺序尝试）

有三种上传方式。优先使用用户的机器上已配置好的方式——速度更快，也能沿用现有配置。只有在没有可用方式时，才建议使用 PicGo Cloud。

第 1 步 — PicGo 桌面应用（如果正在运行）

如果用户已打开 PicGo 桌面应用，其本地服务无需安装或登录即可上传，并会沿用他们在 GUI 中配置的图床。

使用随附脚本（它会先检测服务；如果应用未运行，则不会返回内容）：

node scripts/gui-upload.mjs /abs/path/to/image.png

• 成功时会输出 JSON 数组 [{ "imgUrl": "...", "type": "...", ... }]。
• 告知用户使用了哪个图床，从 type 字段读取（例如“通过你的 PicGo 应用上传（GitHub 上传器）”）。GUI 可能配置的是 PicGo Cloud 以外的图床，因此值得用一行说明。
• 退出代码 2 表示应用未运行 → 转到第 2 步。
• 退出代码 3 表示 GUI 服务已启用身份验证 → 传入 --secret（参见 references/gui-upload-usage.md），或直接转到第 2 步。
• 只有在你指定了特定配置时才会出现退出代码 5 / 6——参见上传到特定配置。

有关剪贴板上传、端口、密钥和逐次上传配置标志，请参见 references/gui-upload-usage.md。

第 2 步 — 确认 PicGo CLI 可用

检查是否已安装 picgo，以及是否支持云端命令：

picgo get uploader --format json

如果失败并提示“unknown command”，或找不到 picgo，则 CLI 缺失或版本过旧。全局安装最新版，然后继续：

npm install picgo -g

如果安装失败（常见原因是 EACCES 权限错误），不要自动尝试 sudo——向用户提供需要他们自行运行的命令（例如 sudo npm install picgo -g，或建议使用 nvm/volta 等 Node 版本管理器以避免使用 sudo），然后等他们安装完成后再继续。

第 3 步 — 通过 CLI 上传（乐观尝试）

第 2 步已告知你当前启用的上传器（来自 picgo get uploader 的输出）。

• 如果是 picgo-cloud，用户需要先登录。检查 picgo cloud auth status --format json（见下方登录说明）。登录后：

  picgo upload /abs/path/to/file --format json
  

• 如果是其他上传器（github、smms 或用户已配置的自定义图床），直接上传——无需登录 PicGo Cloud：

  picgo upload /abs/path/to/file --format json
  

picgo upload --format json 会输出 [{imgUrl, fileName, type, size, ...}]，格式与 GUI 脚本返回的内容相同。只有当标准输出能解析为该 JSON 数组时，才视为上传成功：发生某些错误时（例如未知的 --configName），CLI 会将错误输出到标准输出，但仍以 0 退出。

上传到指定配置

用户通常会保存多个配置（例如，一个“Work” GitHub 仓库和一个“Personal” GitHub 仓库）。只有当用户明确指定某个配置时才这样做（“上传到我的 Work GitHub 配置”“传到 blog 那个图床”）；否则使用默认配置。两种方式都接受相同的选择器，仅对本次上传生效，绝不会更改用户的默认配置：

选择器	含义
--uploader <type>	使用该上传器当前选中的配置（例如，github、smms、picgo-cloud）。
--uploader <type> --configName <name>	使用该上传器中指定名称的配置（不区分大小写）。优先使用此方式。
--configName <name>	在所有上传器中搜索；如果有多个上传器都存在该名称，则失败。
--configId <id>	指定确切的配置 ID（重命名后仍保持不变）；很少需要使用。

• GUI 应用（PicGo ≥ 3.0.3）： node scripts/gui-upload.mjs --uploader github --configName Work /abs/path/a.png。此处始终要同时传入 --uploader 和 --configName：较旧的应用会静默忽略所选配置，并上传到默认图床；只有在知道你指定了哪个上传器时，脚本才能检测到这一情况（退出码为 6）。
• CLI（picgo ≥ 3.1.0）： picgo upload /abs/path/a.png --uploader github --configName Work --format json。使用 picgo uploader list 列出配置名称（当前默认配置会标记为 [Default Config]）。
• GUI 应用和 CLI 使用独立的配置。 GUI 中存在的名称可能在 CLI 中不存在，反之亦然。因此，如果 GUI 提示配置不存在，不要静默地通过 CLI 用同一名称重试——请告知用户并询问其指的是哪个配置。
• 如果选择被拒绝（未知上传器、找不到匹配项或名称不明确），则不会上传任何内容。向用户显示错误消息（其中会列出可用上传器，或名称不明确时的冲突候选项），然后询问用户；不要自行猜测其他配置。

PicGo Cloud 登录

当当前图床为 picgo-cloud 且用户尚未登录时，picgo cloud auth status --format json 会返回以下状态之一：

status	退出码	含义	操作
logged_in	0	令牌有效	继续上传
logged_out	1	没有令牌	引导用户登录（见下文）
invalid	2	令牌已过期或被撤销	引导用户登录（见下文）
error	3	探测失败（网络问题）	这不代表“未登录”——不要催促用户重新登录；重试一次，然后报告结果

登录方式：

• 如果用户已有令牌（例如，从 PicGo Cloud 网页控制台复制的令牌），该操作无需交互且会立即完成：

  picgo login <token>
  

• 如果用户没有令牌，登录需要使用浏览器。不要自行运行 picgo login——没有令牌时，它会启动浏览器 OAuth 流程并阻塞等待回调，在无头或 Agent 环境中会卡住。请改为让用户在自己的终端中运行该命令，并在完成后告知你：

  picgo login
  

PicGo Cloud 提供免费套餐，足以满足日常初次使用的需求。

输出

• 在内部，GUI 脚本和 picgo upload --format json 都会返回相同结构的 JSON 数组：[{imgUrl, fileName, type, size, width, height, ...}]。
• 默认只返回裸 URL。 如果上下文显然是 Markdown 或文档，则改为返回 Markdown 图片：![](imgUrl)（使用合适的替代文本）。对于非图片文件，使用普通链接即可。
• 对于多个文件，结果按输入顺序对应。如果部分上传成功、部分失败，请准确说明哪些文件失败——不要静默省略。
• 不要将任何内容复制到剪贴板；PicGo 会自行处理。

公开链接安全

PicGo Cloud 链接可公开访问——任何人都可以通过链接打开文件，而且删除的文件仍可能被缓存。对于日常用途（截图、要放进文档的图片），直接上传即可。

但对于可能包含敏感信息的非图片文件（合同 PDF、包含内部数据的 zip、名称暗示机密 / 合同 / 身份证 / secret 的任何文件，或者用户的意图听起来像是“存放 / 备份”，而不是“分享”），上传前请确认用户是否接受公开链接。返回任何链接时，都要说明该链接可公开访问。

剪贴板上传

PicGo 可以上传剪贴板中当前的图片，但仅在用户明确提到剪贴板或截图时才这样做（“上传我剪贴板里的图片”“传剪贴板里的图”“托管我刚截的屏”）。Agent 绝不能猜测用户想上传剪贴板内容——其中可能包含无关或敏感信息。

• GUI 应用正在运行：node scripts/gui-upload.mjs --clipboard
• CLI：picgo upload（不带路径参数时会上传剪贴板内容）

如果用户只说“上传一张图片”，既没有提供路径，也没有提到剪贴板，请询问图片在哪里（是文件路径，还是指剪贴板），不要自行猜测。剪贴板上传只能在本地使用——在无头 / 远程环境中不可用。

错误

上传失败的情况并不都一样：PicGo Cloud 大多数业务错误（未登录、文件类型不允许、超出配额）不值得重试——只有网络错误 / 5xx 错误才值得重试。请参阅 references/error-handling.md 中的分类表。需要记住的一条规则是：区分重试可以解决的问题（网络错误 / 5xx，最多重试一次）和无法解决的问题（登录 / 配额 / 类型 / 路径 → 指引用户执行一项具体操作，不要反复重试）。