PicGo 图片上传工具实战指南：从图床配置、写作工作流到本地开发构建

• 桌面应用
• 开发工具
• 插件系统

PicGo 是一款面向高效创作者的开源桌面图片上传工具，其核心目标是把"传图"变成创作流程中无感的一步：无论你是在写博客、记笔记还是编写开发文档，粘贴或拖入图片后，PicGo 自动完成上传并把链接复制到剪贴板。本文以仓库根目录的 README.md 为主体，结合 src/main 目录下的源码实现，系统讲解 PicGo 的图床支持范围、核心功能原理、下载安装方式、开发模式与生产构建流程，帮助你快速上手使用并理解其底层工作机制。

应用概述：PicGo 解决什么问题

PicGo 的定位是"让图片上传无缝融入创作工作流"（原文：make image uploading a seamless part of your creative workflow）。它面向的核心场景是内容创作过程中的高频重复操作——写完博客、记完笔记后，图片还散落在本地磁盘上，需要逐张手动上传到图床再复制链接。PicGo 通过"上传即复制链接"的一步式设计，把这一过程压缩到最低成本。

从仓库实际版本看，当前 package.json 中记录的版本为3.0.2，项目描述为 "A powerful & simple image uploader for creators."，依赖并封装了picgo核心库（picgo: ^3.0.1），GUI 桌面壳与上传核心是分离的。

原生支持的图床

PicGo 开箱即用地支持主流图床，并声明可以通过插件系统无限扩展：

• 国内云厂商：七牛云、腾讯云 COS、又拍云、阿里云 OSS
• 国际 / 开源平台：GitHub、SM.MS(S.EE)、Imgur
• 更多选项（通过插件）：AWS S3、Cloudflare R2、MinIO 等

注意：PicGo 本体不再新增默认的第三方图床支持，新的图床能力需要以插件形式提供。插件开发请参考 PicGo-Core 文档。

从源码看，图床的注册与列举由核心库的picgo.helper.uploader管理。getPicBeds.ts 通过picgo.helper.uploader.getIdList()获取当前所有已注册的图床类型，再与配置picBed.list中保存的可见性设置合并，最终渲染出设置界面中的图床列表——这正是"内置图床 + 插件注册"架构的直接体现。

核心功能与工作流原理

无缝写作流：自动复制链接与多种粘贴格式

上传成功后，链接会自动复制到剪贴板，且支持 Markdown、HTML、URL、自定义模板等格式，粘贴即用。这一行为的实现位于 apis.ts：

• 上传完成后读取配置settings.pasteStyle（默认markdown）与settings.customLink；
• 调用 pasteTemplate.ts 根据风格生成模板；
• 通过handleCopyUrl写入剪贴板，并以系统通知展示上传结果。

其中 pasteTemplate.ts 定义了五种输出模板，自定义模板支持$url、$fileName、$extName三个占位符，$fileName会去除扩展名：

const tpl = { markdown: `![](${url})`, HTML: `<img src="${url}"/>`, URL: url, UBB: `[IMG]${url}[/IMG]`, Custom: formatCustomLink(_customLink, { ...item, url }) }

例如自定义模板$fileName会生成带文件名注释的 Markdown 图片链接，非常适用于批量整理文档配图。

零上下文切换：在编辑器里直接粘贴图片

PicGo 支持把图片直接粘贴进 Obsidian、VS Code、Typora、Neovim、MarkText、思源笔记等编辑器，由 PicGo 在后台完成上传（通过原生支持或社区插件开启）。这种"粘贴即上传"能力的底层对应的是剪贴板上传链路：在 uploader/index.ts 中，uploadWithBuildInClipboard会先尝试从剪贴板读取图片文件路径；若剪贴板中只有图像数据，则通过clipboard.readImage()取出原生图像、编码为 PNG 后写入临时目录，再走统一上传流程，上传完成后自动清理临时文件。

极速上传：多种触发方式与全局快捷键

PicGo 支持拖拽、剪贴板粘贴、快捷键、以及 macOS/Windows 上的右键菜单上传。默认全局快捷键为Command+Shift+U（macOS）/Ctrl+Shift+U（Windows/Linux），且可在设置中自定义。

快捷键机制的源码链路为：内置命令在 builtin.ts 中注册——SHORTKEY_COMMAND_UPLOAD对应uploadClipboardFiles函数；命令的分发由 shortKeyService.ts 中的ShortKeyService负责，它以命令名注册/注销处理器，并通过getShortKeyHandler(command)查询对应处理函数。也就是说，只要按命令名向 ShortKeyService 注册，就能复用整套快捷键能力。

插件生态：图床插件与能力插件

• 图床插件：已有插件支持 AWS S3、Cloudflare R2、MinIO 等第三方图床；
• 能力插件：支持图片压缩、水印、重命名、Markdown 图片迁移等。

插件通过picgo.helper提供的注册机制扩展。例如上传前重命名就是一个典型的 beforeUpload 插件：在 uploader/index.ts 的init()中，通过picgo.helper.beforeUploadPlugins.register('renameFn', ...)注册重命名钩子——当配置settings.rename（手动重命名）或settings.autoRename（自动重命名）开启时，会自动按YYYYMMDDHHmmssSSS格式为文件生成时间戳文件名；手动重命名场景会弹出一个独立的重命名窗口（RENAME_WINDOW），等待用户确认新文件名后再继续上传。

开发者友好：HTTP API 与开源透明

PicGo 自 v2.2.0 起支持通过 HTTP 请求调用上传，方便与其他工具集成。服务端实现在 server/index.ts：

• 服务配置存储在settings.server，默认值为端口36677、主机127.0.0.1、启用开关enable: true；
• 服务启动时会向核心库注入上传适配器（setUploadAdapter），适配器把"剪贴板上传"映射到uploadClipboardFilesWithInfo、"路径上传"映射到uploadSelectedFilesWithInfo；
• 端口配置支持字符串或数字两种写法，启动时统一parseInt为数字。

这意味着你可以用curl之类的方式向本地服务发起上传请求，让第三方脚本、自动化工具也能复用 PicGo 的图床配置。

安装与下载方式汇总

首次使用可参考应用使用文档入门；遇到问题可查阅仓库中的 FAQ.md 以及已关闭的 issues。

本地开发与贡献

官方说明：目前仅在 macOS 与 Windows 上经过测试，Linux 平台并未完全测试。

环境准备

1. 安装 Node.js 与 Git，并熟悉 npm 基础用法；
2. 克隆仓库：git clone https://github.com/Molunerfinn/PicGo.git并进入目录；
3. 使用pnpm安装依赖（请务必使用pnpm，中文 README 特别强调：使用pnpm install将导致未知错误，需先到 pnpm 官网安装 pnpm）；
4. macOS 需要 Xcode 环境，Windows 需要 Visual Studio 环境；
5. 贡献代码前请阅读 CONTRIBUTING.md。

需要说明的是，仓库内同时存在 CONTRIBUTING.md（使用yarn install/yarn dev，内容较旧）与 CONTRIBUTING_EN.md 两份贡献指南，而 README.md 与 package.json 均以pnpm为准，实际开发时请以 README 和 package.json 中的脚本为准。

开发模式

pnpm run dev

开发模式具有热重载特性，但官方提示开发模式不稳定，可能出现进程崩溃，此时只需ctrl+c退出后重新执行pnpm run dev即可。Windows 下开发模式启动后，PicGo 的托盘图标会出现在底部任务栏右下角的应用区。

生产构建

pnpm run build

构建成功后，安装文件会生成在dist目录下。如果网络环境不佳导致electron-builder下载 Electron 二进制失败，可以预先指定国内源：

export ELECTRON_MIRROR="https://npmmirror.com/mirrors/electron/" # Windows 下使用：set ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ （无需引号） pnpm run build

Electron 二进制文件缓存在~/.electron/目录下；如需更新构建版本，删除该目录后重新构建即可。

从 package.json 的脚本可以进一步了解打包细节：pnpm run build对应electron-vite build，而build:win/build:mac/build:linux分别会在构建后用electron-builder --config electron-builder.config.ts生成对应平台的安装包。仓库中还提供了配套脚本，例如 upload-dist.js 用于上传构建产物、electron-builder.config.ts 为打包配置、electron.vite.config.ts 为构建配置。

生态项目与延伸

PicGo 周边有一批配套项目可进一步扩展使用场景：

• vs-picgo：PicGo 的 VS Code 插件版；
• flutter-picgo：PicGo 的手机版 App（支持 Android 与 iOS）；
• PicHoro：另一款兼容 PicGo 配置的手机 App（目前仅 Android）；
• skills：官方 Agent Skills，教会 AI 何时上传、如何用 PicGo 上传；
• dsh-plugin：PicGo 的 DeepSeek Harness 插件。

其中面向 AI 的两项能力（skills 与 dsh-plugin）正是 README 中 "AI-friendly" 定位的落地：当 AI 生成的截图、图表以![](./chart.png)形式留在本地磁盘时，通过上述工具可让 AI 直接调用你已配置的图床完成上传——两者都会复用 PicGo 中已有的图床与插件配置，无需重复设置。

许可证

PicGo 采用 MIT 许可证，版权归 Molunerfinn 所有（Copyright (c) 2017 - Now Molunerfinn）。

• 桌面应用
• 开发工具
• 插件系统