配置文件

picgo 需要配置文件来启动。当你未指定配置文件的时候，picgo 将会使用默认配置文件来启动。

默认配置文件

picgo 的默认配置文件为~/.picgo/config.json。其中~为用户目录。不同系统的用户目录不太一样。

linux 和 macOS 均为~/.picgo/config.json。

windows 则为C:\Users\你的用户名\.picgo\config.json。

自动生成

通常来说你只需要配置 Uploader 即可，所以你可以通过 picgo set uploader 来进入交互式命令行，配置成功后会自动生成配置文件，无需复制粘贴！其他更多的命令可以参考 CLI 命令一章。

注意

同时，填好图床配置之后，请务必通过 picgo use uploader 选择当前要使用的 Uploader。

bash

$ picgo set uploader
? Choose a(n) uploader (Use arrow keys)
  smms
❯ tcyun
  github
  qiniu
  imgur
  aliyun
  upyun
(Move up and down to reveal more choices)

手动生成

如果你要手动生成配置文件，需要自己创建对应的目录、JSON 文件以及至少有如下的配置项（因此还是推荐通过命令行自动生成配置文件）：

json

{
  "picBed": {
    "uploader": "picgo-cloud", // 代表当前默认上传图床为 PicGo Cloud
    "current": "picgo-cloud"
  },
  "settings": {
    "picgoCloud": {
      "token": "" // 通过 picgo login 登录后自动写入，也可以手动填入已有的 token
    }
  },
  "picgoPlugins": {} // 为插件预留
}

如果你已有 PicGo Cloud 的 token，可以直接填入上面的 token 字段；如果没有，运行 picgo login 登录即可自动写入。

picBed

作为 picgo 最主要的配置项，picBed 里包括了当前上传图床，以及所有上传图床的配置。

插件开发者注意

如果一个 Uploader 的名字为xxx，那么它的配置信息会放置在picBed.xxx里。这个将有助于 PicGo 的 electron 版本进行配置。

picBed.uploader

type: string
default: picgo-cloud

表明当前的上传图床是哪个。默认值是picgo-cloud。

picBed.current

作用与picBed.uploader一致，主要是为了兼容 PicGo 的 electron 版本而留下的配置。未来有可能抛弃。

picBed.smms 1.4.7+

SMMS 图床（已迁移到 S.EE）的相关配置。该服务已由原先免费改为收费。请前往 S.EE 控制台获取 token。可以查看 PicGo 的 wiki 进行配置。

迁移说明

如果你之前把 backupDomain 配置成旧域名（例如 smms.app 或 sm.ms），请删除该配置或改成 s.ee，否则可能无法正常上传。

默认值如下：

json

{
  "token": "", // 从 https://s.ee/user/dashboard/ 获取的 API Token
  "backupDomain": "" // 可选。留空将使用默认 s.ee
}

picBed.qiniu

七牛图床的相关配置。可以查看 PicGo 的 wiki进行配置。

默认值如下：

json

{
  "accessKey": "",
  "secretKey": "",
  "bucket": "", // 存储空间名
  "url": "", // 自定义域名
  "area": "z0" | "z1" | "z2" | "na0" | "as0", // 存储区域编号
  "options": "", // 网址后缀，比如？imgslim
  "path": "" // 自定义存储路径，比如 img/
}

picBed.upyun

又拍云的相关配置。可以查看 PicGo 的 wiki进行配置。

默认值如下：

json

{
  "bucket": "", // 存储空间名，及你的服务名
  "operator": "", // 操作员
  "password": "", // 密码
  "options": "", // 针对图片的一些后缀处理参数
  "path": "", // 自定义存储路径，比如 img/
  "url": "" // 加速域名，注意要加 http://或者 https://
}

picBed.tcyun

腾讯云 COS 的相关配置。可以查看 PicGo 的 [wiki](/zh/gui/guide/config#腾讯云 cos) 进行配置。

默认值如下：

json

{
  "secretId": "",
  "secretKey": "",
  "bucket": "", // 存储桶名，v4 和 v5 版本不一样
  "appId": "",
  "area": "", // 存储区域，例如 ap-beijing-1
  "path": "", // 自定义存储路径，比如 img/
  "customUrl": "", // 自定义域名，注意要加 http://或者 https://
  "version": "v5" | "v4" // COS 版本，v4 或者 v5
}

picBed.github

GitHub 图床的相关配置。可以查看 PicGo 的 [wiki](/zh/gui/guide/config#github 图床)进行配置。

默认值如下：

json

{
  "repo": "", // 仓库名，格式是 username/reponame
  "token": "", // github token
  "path": "", // 自定义存储路径，比如 img/
  "customUrl": "", // 自定义域名，注意要加 http://或者 https://
  "branch": "" // 分支名，默认是 main
}

picBed.aliyun

阿里云 OSS 的相关配置。可以查看 PicGo 的 [wiki](/zh/gui/guide/config#阿里云 oss) 进行配置。

默认值如下：

json

{
  "accessKeyId": "",
  "accessKeySecret": "",
  "bucket": "", // 存储空间名
  "area": "", // 存储区域代号
  "path": "", // 自定义存储路径
  "customUrl": "", // 自定义域名，注意要加 http://或者 https://
  "options": "" // 针对图片的一些后缀处理参数 PicGo 2.2.0+ PicGo-Core 1.4.0+
}

picBed.imgur

Imgur 的相关配置。可以查看 PicGo 的 [wiki](/zh/gui/guide/config#imgur 图床)进行配置。

Imgur 已无法新建应用

Imgur 官方已不再支持新建 app。该配置仅适用于已经拥有存量 clientId 的用户；新用户无法再通过旧的应用创建流程获取 clientId。

默认值如下：

json

{
  "clientId": "", // imgur 的 clientId
  "proxy": "" // 代理地址，仅支持 http 代理
}

picBed.proxy

自定义代理配置，picgo 内部使用 request 进行图片上传等网络请求，picBed.proxy 将会被用作 request 的 proxy 配置，目前只支持 HTTP 代理。默认为空表示不设置代理。

示例：

json

{
  "proxy": "http://127.0.0.1:1081",
}

uploader 1.8.0+

PicGo 支持为同一种 uploader 保存多份“命名配置”。

数据的唯一来源（SSOT）存放在 uploader.<type>：

uploader.<type>.configList: 配置列表数组。
uploader.<type>.defaultId: 当前启用配置的 _id。

configList 中每一项都会包含一些元信息字段：

_id（UUID v4）
_configName（同一 uploader 类型下唯一；比较时大小写不敏感）
_createdAt / _updatedAt（时间戳）

为了兼容插件生态，picBed.<type> 会作为当前启用配置的只读镜像，切换配置时会被覆盖更新。

迁移说明

如果你以前是通过 picBed.<type> 配置 uploader，PicGo 会在启动时自动迁移到新结构。

示例：

json

{
  "uploader": {
    "github": {
      "defaultId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "configList": [
        {
          "_id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
          "_configName": "Work",
          "_createdAt": 1700000000000,
          "_updatedAt": 1700000000000,
          "repo": "user/repo",
          "token": "******"
        }
      ]
    }
  }
}

管理/切换配置请参考 CLI 命令（picgo use uploader ...、picgo uploader ...），或使用 Node.js API（ctx.uploaderConfig）。

注意

ctx.uploaderConfig.use、createOrUpdate、copy、rename、remove 会持久化修改；listUploaderTypes、getConfigList、getActiveConfig 用于只读查询。如果只想为本次上传指定一份已有配置，请使用下面的单次上传选项。

单次上传配置 3.1.0+

从 PicGo-Core 3.1.0 开始，可以为每次上传指定图床类型、配置名称或配置 ID，无需先执行 picgo use uploader。这次选择不会修改默认图床、各图床的当前启用配置或本地配置文件，下一次不带参数上传时仍使用原来的默认配置。

三个入口使用相同的参数名称和查找规则：CLI 的 --uploader / --configName / --configId、HTTP /upload 的同名 URL 参数，以及 picgo.upload(input, options) 的选项字段。

参数	作用
`uploader`	已注册的图床类型，例如 `github`。传入后只在该类型内查找配置。
`configName`	已保存的配置名称。去除首尾空白后按不区分大小写的方式匹配，支持中文。
`configId`	已保存配置的 `_id`，精确匹配。配置重命名后 ID 保持不变。

推荐在日常调用中使用便于辨认的 configName。名称只要求在同一图床类型内唯一；不同图床可以拥有同名配置。

传参情况	使用哪份配置
三个参数都不传	沿用原来的默认上传配置，不创建配置副本或覆盖默认图床。
只传 `uploader`	使用该类型 `defaultId` 指向的配置；如果 `defaultId` 缺失或失效，则取该类型的第一份配置。
`uploader` + `configName` 或 `configId`	在指定图床类型内查找对应配置。
只传 `configName` 或 `configId`	在所有已注册图床类型中查找，结果必须唯一。
同时传 `configId` 和 `configName`	优先使用唯一匹配的 ID；ID 找不到或不唯一时再按名称查找。

参数必须是非空字符串。最终找不到配置或无法唯一确定时会明确报错，不会悄悄改用默认图床。指定了不存在的 uploader 也会报错，不会扩大到其他类型继续查找。只传图床类型但该类型没有配置时会报错；picgo-cloud 可以直接使用当前登录状态，但这些参数不能切换 PicGo Cloud 账号。

如果需要配置 ID，可以读取本地配置文件中的 uploader.<type>.configList，或调用 picgo.uploaderConfig.getConfigList(type)，使用对应条目的 _id。参数只引用已经保存的配置，不用于在 URL 中传入 token 等图床凭据。

使用示例见 CLI 上传、HTTP 上传和 Node.js 上传。

配置隔离与持久化

带有这些选项的上传会使用独立的配置副本，不同请求可以同时使用不同配置。插件显式调用 saveConfig / removeConfig 仍然会写入配置文件；“不改写配置”指的是本次图床选择本身。插件接入方式见单次上传上下文。

picgoPlugins

这个配置项将会将所有插件名放置进去。主要用于判断插件是否被启用或者禁用。 picgo 自动生成，不需要配置！

示例：

json

{
  "picgo-plugin-xxx": true, // 该插件被启用
  "picgo-plugin-yyy": false // 该插件被禁用
}

settings

一些与具体 uploader/transformer/plugin 无关的通用设置。

settings.server 2.0+

本地服务配置（用于 picgo server 以及程序化启动本地服务）。

settings.server.port（number | string）：服务端口，默认 36677。
settings.server.host（string）：服务 host，默认 127.0.0.1。
settings.server.secret（string，可选）：本地服务鉴权 secret。

如果设置了 secret，会对 POST /upload 和所有插件路由启用鉴权。最终 secret 按优先级解析：CLI --secret → 环境变量 PICGO_SERVER_SECRET → 配置 settings.server.secret。值会被 trim；仅空白会禁用鉴权。

示例：

json

{
  "settings": {
    "server": {
      "port": 36677,
      "host": "127.0.0.1",
      "secret": "your-shared-secret"
    }
  }
}

settings.picgoCloud 2.0+

PicGo Cloud（https://cloud.picgo.app）登录与同步偏好配置。

settings.picgoCloud.token（string）：通过 picgo login（cloud.picgo.app）或浏览器登录保存的 token。仅本地保存（不参与同步）。
settings.picgoCloud.encryptionMethod（string）：配置同步的加密方式偏好。
- e2ee → 端到端加密
- sse → 服务端加密
- auto → 由同步流程决定；未配置时默认

同步时这两个字段会被视为本地值，不会被云端覆盖。关于登录与手动同步的使用方式，请参考命令行文档：picgo login 与 picgo config sync。

示例：

json

{
  "settings": {
    "picgoCloud": {
      "token": "YOUR_TOKEN",
      "encryptionMethod": "e2ee"
    }
  }
}

settings.urlRewrite.rules 1.8.1+

可选的 URL 重写规则。配置后，PicGo 会在 Uploader 执行结束之后、afterUploadPlugins 执行之前 对上传结果中的 imgUrl 做 URL rewrite。

type: Array<Rule>
default: 未配置（不执行 rewrite；不会输出警告）

每条规则支持：

match (string, required): JavaScript RegExp 的源字符串（不需要写两侧的 /）。
replace (string, required): 替换字符串（支持 $1、$2... 分组引用）。
enable (boolean, optional): 默认 true；只有显式设置为 false 才会禁用该规则。
global (boolean, optional): 对应正则的 g flag；默认 false。
ignoreCase (boolean, optional): 对应正则的 i flag；默认 false。

行为说明：

规则按数组顺序依次匹配；对每张图片只应用第一条命中的启用规则（First Match Wins）。
如果 rewrite 导致 imgUrl 发生变化，会把原始 URL 保存到 originImgUrl（只会设置一次，不会被覆盖）。
match 无法编译成正则时会输出 error 并跳过该规则，上传流程不会失败。
rewrite 结果为空字符串时会输出 warning，但仍会继续。

对插件开发者 / Node.js 调用方的影响

afterUploadPlugins 拿到的 ctx.output 里 imgUrl 已经是 重写后的 值；如需上传器产出的原始 URL，请读取 originImgUrl。
Node.js API picgo.upload() 返回的 IImgInfo[] 里 imgUrl 也是 重写后的 值；如需重写前的值，请读取 originImgUrl。
只有当 PicGo 实际发生 URL 重写时才会设置 originImgUrl；否则它会保持为 undefined。

示例

示例（简单前缀替换 / 切换到 CDN）：

把：

https://example.com/images/2026/1.png
重写为 https://cdn.example.com/blog-images/2026/1.png

json

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "https://example.com/images/",
          "replace": "https://cdn.example.com/blog-images/"
        }
      ]
    }
  }
}

示例（忽略大小写：统一扩展名）：

把：

https://cdn.example.com/blog-images/2026/1.PNG
重写为 https://cdn.example.com/blog-images/2026/1.png

json

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "PNG",
          "replace": "png",
          "ignoreCase": true
        }
      ]
    }
  }
}

示例（global：替换 URL 中所有下划线）：

把：

https://cdn.example.com/blog_images/2026/hello_world.png
重写为 https://cdn.example.com/blog-images/2026/hello-world.png

json

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "_",
          "replace": "-",
          "global": true
        }
      ]
    }
  }
}

正则与转义

match 是 JavaScript 正则表达式的源字符串。进阶用法中你可能需要在 JSON 字符串里转义反斜杠，例如要匹配 . 需要写成 \\.。

进阶：分组引用（$1、$2...）

把：

https://example.com/images/2026/1.png
重写为 https://cdn.example.com/blog-images/2026/1.png

如果 match 里用括号捕获了 URL 的某一段，就可以在 replace 里用 $1、$2... 引用（例如 $1 表示第 1 个分组，$2 表示第 2 个分组）。在下面这个例子里，$1 会捕获到 images，$2 会捕获剩余路径（2026/1.png）：

json

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "^https://example.com/(images)/(.*)$",
          "replace": "https://cdn.example.com/blog-$1/$2"
        }
      ]
    }
  }
}

进阶示例（把 GitHub raw URL 重写为 jsDelivr）：

把：

https://raw.githubusercontent.com/user/repo/main/path/to/1.png
重写为 https://cdn.jsdelivr.net/gh/user/repo@main/path/to/1.png

json

{
  "settings": {
    "urlRewrite": {
      "rules": [
        {
          "match": "^https://raw.githubusercontent.com/([^/]+)/([^/]+)/([^/]+)/(.*)$",
          "replace": "https://cdn.jsdelivr.net/gh/$1/$2@$3/$4"
        }
      ]
    }
  }
}

config.snapshot.json 2.0+

运行 picgo config sync 后，PicGo 会在 baseDir（与 config.json 同目录）生成 config.snapshot.json，作为三路合并的基线快照，格式为 { version, updatedAt, data } 并保留注释。

一般不建议手动修改该文件。若它不存在，下一次同步会重新生成，并以本地配置为准回填云端配置。

transformer

这个配置项主要用于存放第三方插件里的 Transformer 的相关配置。

插件开发者注意

如果一个 Transformer 的名字为xxx，那么它的配置信息会放置在transformer.xxx里。这将有助于 PicGo 的 electron 版本进行配置。

默认值：{}

picgo-plugin-*

如果你为 picgo 开发了一个插件，如果这个插件本身需要一些配置项，那么这个插件对应的配置应该直接放置在配置文件下的同名配置里：

示例：

json

"picgo-plugin-xxx": {
  "config1": "",
  "config2": ""
}

它是如何工作的？

默认配置文件

picBed

settings

get

cloud

config

server

upload|u

初始化

上传

PicGo Cloud

事件监听

生命周期插件

加载第三方插件

配置文件 ​

默认配置文件 ​

自动生成 ​

手动生成 ​

picBed ​

picBed.uploader ​

picBed.current ​

picBed.smms 1.4.7+ ​

picBed.qiniu ​

picBed.upyun ​

picBed.tcyun ​

picBed.github ​

picBed.aliyun ​

picBed.imgur ​

picBed.proxy ​

uploader 1.8.0+ ​

单次上传配置 3.1.0+ ​

picgoPlugins ​

settings ​

settings.server 2.0+ ​

settings.picgoCloud 2.0+ ​

settings.urlRewrite.rules 1.8.1+ ​

对插件开发者 / Node.js 调用方的影响 ​

示例 ​

config.snapshot.json 2.0+ ​

transformer ​

picgo-plugin-* ​

配置文件

默认配置文件

自动生成

手动生成

picBed

picBed.uploader

picBed.current

picBed.smms 1.4.7+

picBed.qiniu

picBed.upyun

picBed.tcyun

picBed.github

picBed.aliyun

picBed.imgur

picBed.proxy

uploader 1.8.0+

单次上传配置 3.1.0+

picgoPlugins

settings

settings.server 2.0+

settings.picgoCloud 2.0+

settings.urlRewrite.rules 1.8.1+

对插件开发者 / Node.js 调用方的影响

示例

config.snapshot.json 2.0+

transformer

picgo-plugin-*