图片上传引擎 PicGo/PicGo-Core

特别鸣谢

Modelflare
Modelflare：满血、稳定、绝不掺水。全球 SOTA 模型，成本更低。

Castaly
Castaly：满血、不放大。40+ 图像与视频模型，包含 NSFW。

NocoBase
AI + 无代码，构建可靠的业务系统

Neon
面向团队与智能体的高速 Postgres 数据库

PicGo-Core

picgo-core
一个图片上传工具。同时支持命令行和 API。还支持插件系统，想看有哪些好用的插件，可以去看 Awesome-PicGo。

更多细节请见 PicGo 的主页。

Typora 原生支持 PicGo-Core。

安装

PicGo 要求 Node.js >= 20.19.0 或 >= 22.12.0。更早的 PicGo 版本（<= v1.5.x）用 Node.js >= 16 就够了。因为我们需要 ES Module 支持的稳定性。

全局安装

npm install picgo -g

or

yarn global add picgo

本地安装

npm install picgo -D

or

yarn add picgo -D

用法

在命令行中使用

PicGo 默认使用 SM.MS(S.EE) 作为上传图床。

查看帮助：

$ picgo -h

Usage: picgo [options] [command]

Options:
-v, --version output the version number
-d, --debug debug mode
-s, --silent silent mode
-c, --config <path> set config path
-p, --proxy <url> set proxy for uploading
-h, --help display help for command

Commands:
install|add [options] <plugins...> install picgo plugin
uninstall|rm <plugins...> uninstall picgo plugin
update [options] <plugins...> update picgo plugin
set <module> [name] [configName] configure config of picgo modules (uploader/transformer/plugin)
upload|u [input...] upload, go go go
use [module] [name] [configName] use module (uploader/transformer/plugin) of picgo
get get current picgo module config (uploader/transformer/plugins)
i18n [lang] change picgo language
uploader manage uploader configurations
server [options] run PicGo as a standalone server
login [token] login to cloud.picgo.app
logout logout from cloud.picgo.app
cloud manage PicGo Cloud
help [command] display help for command

按路径上传图片

picgo upload /xxx/xx/xx.jpg

用已保存的配置上传

用 --configName 为单次上传指定一份已保存的配置。同一个名字在多种上传器类型里都存在时，加上 --uploader。也可以用 --configId；ID 唯一匹配时优先于名字，ID 没匹配上而同时提供了名字时，回退到名字。

picgo upload ./photo.png --configName=Work
picgo upload ./photo.png --uploader=github --configName="Work Images"
picgo upload ./photo.png --uploader=github --configId=your-config-id --configName=Work

从剪贴板上传，使用已保存的配置。

picgo upload --configName=Work

这些选项的查找规则与 HTTP 和 SDK 上传相同，不会改动已保存的默认值。不加这些选项时，picgo upload 保持原有的默认行为。上传后本地输入文件会保留；只有 PicGo 创建的临时 multipart 文件和剪贴板图片会被清理。剪贴板文件名沿用现有的 YYYYMMDDHHmmssSSS.png 格式。

从剪贴板上传图片

从剪贴板读取的图片会转换成 png bash picgo upload

感谢 vs-picgo 和 Spades-S 提供从剪贴板上传图片的方法。

作为服务器运行 bash picgo server -p 36677 -h 127.0.0.1

为单次上传选择配置

在 POST /upload 里加上 uploader、configName 或 configId，就能为这次请求选用一份已保存的配置。配置名可读性更好，推荐使用。名称里含空格、中文或其他特殊字符时，要做 URL 编码： js const url = new URL('http://127.0.0.1:36677/upload')
url.searchParams.set('uploader', 'github')
url.searchParams.set('configName', 'Work')

const response = await fetch(url, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ list: ['/absolute/path/photo.png'] })
})
const result = await response.json()

同样的查询参数也适用于：空请求体的剪贴板上传、不带 list 或 list 为空的 JSON、以及用 files 字段的 multipart 上传。如果启用了服务器鉴权，请带上原有的 Authorization: Bearer <secret> 请求头。

| 上传选项 | 行为 |
| 不带上传选项 | 沿用原有的默认上传行为。 |
| uploader=github | 使用 GitHub 当前选中的配置（defaultId，取不到时回退到它的第一份配置）。 |
| uploader=github&configName=Work | 在 GitHub 下查找 Work，忽略大小写和首尾空白。 |
| configName=Work | 搜索已注册的上传类型；必须恰好匹配到一份配置。 |
| configId=<id> | 按精确 ID 查找，可用 uploader 限定范围。配置改名后 ID 保持不变。 |
| 同时给出 configId 和 configName | 先按 ID 唯一匹配；无法唯一确定时，再按名称查找。 |

上传类型未知、配置缺失或有歧义、上传参数为空或重复时，返回 HTTP 400，响应体为 { success: false, result: [], items: [], code, message }。message 会说明查找失败或存在歧义的原因；名称在多个类型间重复时，请指定 uploader 来消歧。上传选项无效时，绝不会回退到全局默认上传类型。原有的鉴权失败仍返回 HTTP 401。
上传选项不会改变全局默认值，也不会把请求的配置保存到磁盘。并发请求可以使用不同配置。插件如果通过生命周期处理函数收到的上下文读取配置，就能看到请求的配置；如果插件缓存了全局配置，可能需要适配。显式的插件持久化和 Cloud 会话维护保持原有行为。uploader=picgo-cloud 使用当前 Cloud 登录；这些选项不会切换 Cloud 账号。

提供自定义内部服务器上传适配器的应用，必须把可选的 UploadOptions 参数转发给 picgo.upload：uploadPaths(paths, options) 转发给 picgo.upload(paths, options)，uploadClipboard(options) 转发给 picgo.upload(undefined, options)。现有适配器仍可处理不带选择器的请求，但忽略这些选项就会忽略请求的目标。

登录 PicGo Cloud bash picgo login

or

picgo login <token>

退出 PicGo Cloud bash picgo logout

检查 PicGo Cloud 登录状态

用 picgo cloud auth status 查看当前 PicGo Cloud 登录状态，不会触发交互式登录。检查是非阻塞的：本地没有 token 时立即返回，不发任何网络请求。
bash
picgo cloud auth status

machine-readable output

picgo cloud auth status --format json

该命令会设置进程退出码，方便在脚本中使用：

| 状态 | 含义 | 退出码 |
| logged_in | Token 有效 | 0 |
| logged_out | 本地没有 token | 1 |
| invalid | Token 存在但被服务器拒绝（401） | 2 |
| error | 探测失败（网络 / 服务器错误） | 3 |

--format json 输出为单行，例如： json {"status":"logged_in","loggedIn":true,"user":"someone","plan":1}

查看当前模块配置

用 picgo get 读取当前选中的 picgo 模块。每个子命令都支持 --format pretty|json（默认 pretty）。
bash

current uploader type (resolved as picBed.uploader -> picBed.current -> picgo-cloud)

picgo get uploader

current transformer (defaults to path)

picgo get transformer

installed plugins with enabled/disabled state

picgo get plugins

machine-readable output

picgo get uploader --format json
picgo get plugins --format json

json 模式下每条命令输出一行可解析内容，例如： json {"uploader":"github"} {"transformer":"path"}
{"plugins":[{"name":"picgo-plugin-xxx","enabled":true}]}

管理上传器配置从 v1.8.0 起，PicGo-Core 支持每个上传器配置多份配置，和 Electron 版 PicGo 的配置方式一样。

你可以用 picgo set uploader <type> [configName] 配置不同的上传器配置。

也可以用 picgo use uploader <type> [configName] 在不同上传器配置之间切换。

例如： bash picgo set uploader github Test

picgo use uploader github Test

想看更多细节，可以用 picgo uploader -h 查看上传器管理的帮助： bash Usage: picgo uploader [options] [command]

Options:
-h, --help display help for command

Commands:
list [type] list uploader configurations
rename <type> <oldName> <newName> rename a config
copy <type> <configName> <newConfigName> copy a config (does not switch current uploader)
rm <type> <configName> remove a config

初始化 picgo 插件模板

注意：插件模板初始化器已迁移到独立的 picgo-init 包。

你可以用下面的命令初始化 picgo 插件模板： bash
npx picgo-init plugin <your-plugin-folder>

在 node 项目中使用

Common JS
js
const { PicGo } = require('picgo')

ES Module
js
import { PicGo } from 'picgo'

API 用法示例 js const picgo = new PicGo()

// upload a picture from path
picgo.upload(['/xxx/xxx.jpg'])

// upload a picture from clipboard
picgo.upload()

SDK 在第二个参数里接受同样的选择器： js
import { PicGo, UploadOptionError } from 'picgo'

const picgo = new PicGo()

try {
await picgo.upload(['/absolute/path/photo.png'], {
uploader: 'github',
configName: 'Work'
})

// A globally unique name can identify both the uploader and its configuration.
await picgo.upload(undefined, { configName: 'Work' })
} catch (error) {
if (error instanceof UploadOptionError) {
console.error(error.code, error.message)
} else {
throw error
}
}

上传选项无效时，会在处理输入之前直接 reject 上传 promise。错误码有 INVALID_UPLOAD_OPTION、UNKNOWN_UPLOADER、UPLOAD_CONFIG_NOT_FOUND 和 UPLOAD_CONFIG_AMBIGUOUS。在限定作用域的上传上下文里临时调用 setConfig/unsetConfig，只影响这一次上传；显式调用 saveConfig/removeConfig 仍然会持久化。已有的 SDK 调用如果不传上传选项，行为保持不变。

开发

仓库开发请使用 Node.js >= 22.13 和 pnpm 11.7.0。包管理器版本固定在 package.json 里；pnpm-workspace.yaml 记录了允许执行的 esbuild 安装脚本。这套工具链要求不影响 PicGo 发布后的运行时要求。
bash
pnpm install --frozen-lockfile
pnpm lint
pnpm test
pnpm build

文档

想看更多细节，可以查阅文档。