PicGo 图床客户端：写 Markdown 时图片一键上传

PicGo 出 3.0 了。10 月 5 号发的 3.0.3，老 2.x 那套 vue-cli 界面整个扔掉，换成了 React 19 + Tailwind 4，看着年轻不少。

我在 Windows 上把它从源码编了一遍，界面名改成「源码湾图床」，做成免安装版。能跑，但有几件事得先说清楚，不然你解压完会骂人。

PicGo 能干什么

一句话：它是「把本地图片变成外链」这一步的快捷键，写 Markdown 的人最需要它。

按用途对号入座——

• 写博客、写文档：截图 → 粘贴 → 自动上传 → 自动把 Markdown 链接贴回光标处
• 图床不止一个：GitHub、七牛、阿里云 OSS、腾讯 COS、S3、SM.MS 都能配，随时切
• 批量传图：一次拖十几张进去，传完一次性复制所有链接
• 剪贴板直传：截图后按个快捷键就上传，不用先存成文件
• 给别的程序调用：自带一个本地 HTTP 服务，Typora、Obsidian、脚本都能往里塞图
• 想自己掌控图片：配成自己的图床或对象存储，图片不会哪天跟着免费图床一起没了

它不是图片管理软件——不修图、不压缩相册、不做图库整理。就是上传这一个动作。

核心功能亮点

• 拖拽 / 剪贴板 / 右键上传，三种入口
• 链接格式自定义：Markdown、HTML、URL、UBB 随便选，还能套自定义模板
• 多图床并存：配几个都行，上传时切一下
• 内置 HTTP 服务：别的软件能通过本地端口调它上传，这是很多人不知道的功能
• 插件市场：图床、压缩、水印都能靠插件补
• 上传历史：传过什么都留着，能找到旧链接
• 深色主题：3.0 新界面自带
• 免安装版：解压双击，不用装 Node、不用装运行库

一、它不是装完就能用的软件

这是我最想提前讲的一点。

PicGo 默认图床是 PicGo Cloud —— 官方的云服务，要注册登录。你要是不登录、也不自己配一个图床，拖进去的每一张图都会失败，然后弹一句「请检查设置和网络」。

我第一次跑就这样，盯着那个上传失败的提示看了半天才反应过来：它只是个「上传客户端」，图存哪儿是你自己的事。

所以「配图床」这一步绕不过去。GitHub 仓库、阿里云 OSS、腾讯云 COS、七牛云、又拍云、SM.MS、Imgur，七选一，填几个参数。

GitHub 最省钱：仓库名填 用户名/仓库名，分支填 main，Token 去 GitHub 设置里生成一个只勾 repo 权限的，存储路径随便写个 images/。

填完右上角记得点「设为默认配置」。不点的话，它还会继续用 PicGo Cloud，你还是一样传不上去。

二、编译踩了五个坑

仓库地址 https://github.com/Molunerfinn/PicGo，tag v3.0.3，源码包 3.2MB。这个仓库现在只有源码，node_modules 得自己装，好在一条 pnpm install 就够。

技术栈：electron-vite 4 + Vite 7 + React 19 + TypeScript 5.9 + Tailwind 4，包管理 pnpm 10.29.2，Electron 38.7.2。

坑 1：postinstall 崩了。 electron-builder install-app-deps 在我机器上直接挂，退出码 3221226505（0xC0000409）。查了一下，这一步是给原生模块重编译，PicGo 里没有需要重编的原生模块（node_modules 里那几个 .node 文件都是预编译好的 rollup / tailwind / lightningcss 二进制），跳过不影响。依赖本身是装完的，719MB。

坑 2：electron-builder 下 Electron 报 502。 它默认从 github.com/electron/electron/releases 拉 110MB 的运行时，我这边直连被网关拦了。解法是环境变量：

export ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/
export ELECTRON_BUILDER_BINARIES_MIRROR=https://npmmirror.com/mirrors/electron-builder-binaries/

.npmrc 里写 electron_mirror= 没用，electron-builder 只认这两个环境变量。

坑 3：命令行参数全部无效。 打出来的 exe 一跑就报 bad option: --remote-debugging-port=9223，窗口都不弹。查了十几分钟，根因是我这个终端环境里有个 ELECTRON_RUN_AS_NODE=1 —— 有这个变量，Electron 会把自己当纯 Node 解释器，所有 Chromium 参数全当非法。unset 掉就好了。

这坑跟 PicGo 没关系，但如果你在 VS Code 的集成终端、或某些 IDE 的内置 shell 里跑 Electron 项目，八成会撞上。

坑 4：GPU 进程崩溃直接退出。 日志里刷一串 GPU process exited unexpectedly: exit_code=-1073741819，然后一句 FATAL: GPU process isn't usable. Goodbye. 直接关掉。

我这边是沙箱环境限制，普通物理机大概率不触发。但虚拟机、远程桌面、云主机、老显卡驱动上会。给 exe 加 --disable-gpu 就能起（我这台还得再加 --no-sandbox --disable-gpu-sandbox）。

坑 5：改完名字 logo 全裂。 这个最有意思 —— 我以为是打包漏了文件，查下来是原项目自带的 bug：代码里图片写的是 src="/squareLogo.png" 这种绝对路径，而 electron-vite 生产构建的 base 是 ./，在 file:// 协议下 /xxx.png 会被解析成盘符根目录，不是应用目录。

也就是说，原版 PicGo 3.0.3 里迷你窗口、工具箱那几个 logo，在官方安装包里本来就是裂的，只是没人在意。我改成 ./brand-logo.png 之后才正常。

三、品牌化改了哪些地方

按惯例，站内显示名统一改成「源码湾」。

• 窗口标题、托盘标题 → 源码湾图床
• 侧栏品牌、关于页名称 → 源码湾图床
• 三处远程 logo（指向 pics.molunerfinn.com）→ 换成打包在本地的一套图标，浅色 / 暗夜两个版本跟着主题自动切
• 产品名、exe 名 → 源码湾图床.exe
• 应用图标（16~256 多尺寸 ico）、窗口图标、favicon
• 6 条中文文案：设置页标题、配置损坏提示、重启提示、排查工具标题、插件搜索提示等

没动的：PicGo Cloud（官方云服务，改了就是骗人）、PicGo-Server（内置服务的技术名）、赞助作者、检查更新。

改完之后 %APPDATA% 下的配置目录还是 picgo，这个改不了也不用改 —— Electron 的 app.getName() 取的是 package.json 的 name，不是 productName。

四、内置 HTTP 服务，很多人不知道有这功能

PicGo 默认在 127.0.0.1:36677 起一个 HTTP 服务，给 Typora、Obsidian、VS Code 插件这类编辑器调用的。

我一开始按文档 curl GET /heartbeat，404。翻源码才发现路由只认 POST：

curl -X POST http://127.0.0.1:36677/heartbeat
{"success":true,"result":"alive"}

启动日志里它自己会打一句警告：认证已关闭，任何人都可以上传图片。本机自己用没事，要是把端口映射到公网，等于给互联网开了个免费图床。

五、深色主题和插件市场

3.0 加了完整的深色主题，侧栏底部那个小月亮点一下就切，不用重启。

插件走 npm，在搜索框里直接搜包名，会列出 s3、s3-lls、s3-continued 这些第三方实现，带版本号和作者。

安装就是后台 npm i，装完重启生效。

六、实测数据

• 源码 3.2MB，node_modules 719MB
• 打包产物：压缩包 176.2MB，解压 324MB（Electron 应用的通病，app.asar 一个就 182MB）
• 解压耗时 12.9 秒（Python zipfile，中文路径无乱码）
• 冷启动到可用约 10 秒，6 个进程（主进程 + 渲染 + GPU + 网络 + 两个隐藏窗口）
• 内置服务端口 36677 启动即监听

配置全在 %APPDATA%\picgo\data.json，一个 JSON 文件，备份就是抄这一个文件。

七、缺点，一条条说

1. 不配图床就是空壳。 上面说过了，这是产品定位决定的，不是 bug，但很多人会误会。
2. 界面里还留着四个官方入口：官网、GitHub、文档、检查更新，全部指向 picgo.app。这些我没改 —— 改了是骗人。代价是界面里「源码湾图床」和「PicGo 官网」并存，看着不统一。二次分发开源软件躲不掉这个。
3. 内置 HTTP 服务默认无认证。 默认就开着，默认就裸奔，日志只警告一句。
4. 体积大。 324MB 的目录，装完的软件里算胖的。想要轻的，去看我们收录的兰空图床（PHP，十几 MB）。
5. 单机单人。 它是桌面客户端，配置在自己电脑上，团队没法共享一套图床配置。多人协作还是得看服务端方案。
6. 我没测到真实上传成功这一环。 配置表单、插件市场、内置服务、界面全部验过了，但最后一步「图片真的传进你的仓库 / OSS / 七牛」得你自己填账号才能测。我手里没有你的 Token，这条我不编。

八、怎么用

下下来是个 zip，解压到 D 盘任意目录（别放 C:\Program Files，那儿要管理员权限），双击「双击启动.bat」，或者进「程序」文件夹双击「源码湾图床.exe」。

第一次启动是英文界面的话：设置 → 通用 → 选择语言 → 简体中文。切换立即生效。

上传流程那页有几个开关值得改：「上传后自动复制 URL」默认开着，配合下面「自定义链接格式」能直接复制成 Markdown 图片语法，写文档的时候很省事。

相册页存的是你传过的记录，按图床分类统计，可以按时间筛选。

九、自己动手的成本

PicGo 的源码包只有 3.2MB，看着轻，编译这一趟一点都不轻：

1. 依赖 719MB。pnpm install 要装七百多个包，其中的 electron-builder install-app-deps 在我机器上直接崩（退出码 0xC0000409），得先查清楚「这项目没有要重编的原生模块」才敢跳过
2. Electron 运行时 110MB。electron-builder 默认从 GitHub 拉，直连被网关拦成 502，只能挂 ELECTRON_MIRROR / ELECTRON_BUILDER_BINARIES_MIRROR 两个环境变量绕过去 —— 写进 .npmrc 它不认
3. 终端环境。ELECTRON_RUN_AS_NODE=1 会让打出来的 exe 把所有 Chromium 参数当非法，报 bad option: --remote-debugging-port=9223，窗口都不弹。VS Code 集成终端、某些 IDE 的内置 shell 里八成会撞上
4. GPU。虚拟机、远程桌面、云主机、老显卡驱动上大概率撞 GPU process isn't usable. Goodbye.，得手动加 --disable-gpu
5. 改名字。原项目 logo 写的是绝对路径 /squareLogo.png，file:// 协议下会被解析到盘符根目录，得逐个改成 ./ 才不裂

我的记录：从 pnpm install 到第一次成功出窗口，大半天；光 postinstall 那一下崩溃就够调一晚上。下面那个包是编好、改完名字、跑通过的，双击就用。

十、包里有什么

重新编译的命令：pnpm install → pnpm build → pnpm exec electron-builder --config electron-builder.config.ts --win dir --x64。Node 要 22。

原项目 MIT 协议，允许修改和再分发，LICENSE 在源码目录里，一个字没动。

两个小提醒：

1. 建议先「转存到自己网盘」再下载——直接下载的链接容易失效，转存后就是你自己的了，随时能下；
2. 手机上操作：点开链接 → 右下角「保存到网盘」→ 回夸克 App 的「我的网盘」里下载。

装之前先确认两件事：Windows 10 以上（64 位）、自己准备一个图床。这条最要紧——PicGo 本身不带存储，不配图床的话你拖进去的每张图都会失败。