最近思源笔记的 S3 插件更新到 v1.0.2，好多人在群里问怎么配 PicList 做导出。我之前在 v1.0.0 的时候踩过不少坑，这次正好把完整流程捋一遍，从存储桶准备到 PicList 参数设置，再到思源笔记里的目录映射，一步步来。
先说结论：这俩搭配的核心其实就是一套标准 S3 协议接龙。PicList 负责把图片传上去，思源笔记通过插件把附件也丢到同一个存储桶，两边只要路径规则统一，就能实现稳定的图床管理和附件导出。v1.0.2 相比之前版本，主要修了自定义端点的兼容性和路径前缀的解析问题。
1. 为什么要用 S3 插件 + PicList 这套组合
1.1 传统附件管理方式的痛点
思源笔记默认把图片和附件存在本地工作空间里，配合内置的资源文件机制，单机用确实省心。但只要涉及多设备同步、文章发布到博客、或者和别人协作，本地附件的局限性就出来了：
- 局域网同步盘同步文件时经常遇到文件锁冲突，尤其是 Windows 环境下
data目录被占用的情况。 - 发布文章时图片还是本地相对路径，复制到博客后台就全部裂开。
- 别人拿到
.sy.zip包解压后，如果没同步对应资源目录，笔记里的图全是红叉。
1.2 S3 协议存储的优势
S3 协议的兼容性是个非常成熟的东西，主流的云厂商对象存储都支持，等于你写一次接口逻辑，可以对接一堆后端。思源笔记 S3 插件把它用于附件存储，好处很明显：
- 附件以对象形式存放，天然支持版本管理和生命周期规则。
- 不走本地文件系统，不存在锁冲突问题。
- 结合 PicList 的图床管理，图片链接可以拿到任意平台使用。
1.3 v1.0.2 更新带来的改变
这次版本更新有几个点值得关注：
- 重写了路径拼接逻辑，之前
prefix末尾有没有斜杠经常导致目录层级错乱，现在插件会统一格式化。 - 优化了自定义域名回源时的 URL 生成规则，配置了 CDN 或者反向代理之后，导出的链接不再出现多级路径拼接错误。
- 对 S3 兼容服务的 region 自动识别做了改进，对于非 AWS 主流的服务商，不再强制要求
us-east-1。
我实测下来，这几个改动刚好都踩在之前闹心的位置上，尤其是路径拼接，之前配 MinIO 的时候真是折腾得够呛。
2. 配置前的准备工作
2.1 注册并创建存储桶
无论你选哪家对象存储服务，第一步都是创建存储桶。以常见的兼容 S3 的服务为例，你需要：
- 登录控制台，进入对象存储页面。
- 创建 Bucket，名字建议全小写，比如
siyuan-assets。部分服务商对 Bucket 命名有限制，不能有大写字母和下划线。 - 地域选择就近的，比如你在国内就选华东或华北节点，海外就选离你近的节点。
注意：存储桶的访问权限建议设为“私有读写”，因为 PicList 和插件都走签名认证，不需要公开读。公开读写容易被人刷流量，对象存储的流量费可不便宜。
2.2 获取访问密钥
每家服务商叫法略有不同，但核心就是一对 Key：
- AccessKey：相当于用户名。
- SecretKey：相当于密码。
生成后一定要马上保存，因为大多数平台只在创建时显示一次 SecretKey。如果弄丢了就得重新生成，重新生成后旧的应用全部失效。
2.3 安装 PicList
PicList 是 PicGo 的一个分支项目，对 S3 协议的支持更完整，配置界面也更友好。去官网下载对应系统的安装包，目前 Win 和 macOS 都有现成的安装包，Linux 下也有 AppImage 版本。
安装完打开，界面分成“上传区”“相册区”“配置区”三大块。相册区就是你上传过的图片历史列表，这个功能对于后期整理笔记里用过的图特别实用。
3. PicList 端配置详解
3.1 添加 S3 兼容存储桶
在 PicList 左侧菜单找到“图床设置”，选择“S3 兼容”，然后点“新建”。这里要填的参数比普通图床要多，逐个解释：
- 应用 ID：填你的 AccessKey。
- 应用密钥：填你的 SecretKey。
- 存储桶：填 Bucket 名称。
- 区域：就是存储桶所在地域的代码。例如 AWS 的
ap-northeast-1（东京）、阿里云 OSS 的oss-cn-hangzhou。如果你用的是 MinIO 这类自建服务，区域可以随便填，比如us-east-1，因为 MinIO 不校验这个。 - 自定义节点：这是 S3 兼容配置最容易出错的地方。很多服务商要求填带
https://的完整地址，格式一般是https://{bucket}.{endpoint}或者不带 bucket 的纯 endpoint。分不清的时候，建议先试不带 bucket 的格式，比如https://s3.cn-north-1.jcloudcs.com，如果不行再试带 bucket 的格式。 - 路径前缀：这里填写你希望文件在 Bucket 里存放的目录。比如填
siyuan/，那 PicList 上传的图片都会进siyuan/这个“文件夹”下。这里有一个重要的规则：前缀要以/结尾，否则存储服务会把你的前缀当成文件名的一部分，路径就乱了。
3.2 路径格式的取舍
PicList 里有个可以自定义上传路径的选项，默认是日期格式{year}/{month}/{day}。我建议如果你主要给思源笔记用，路径格式不要设太深，直接设一个固定前缀就够了。因为思源插件导出的时候会按自己的规则重建目录，如果两边路径规则都设得很复杂，容易出现资源文件路径错位的问题。
我现在的配置是：
- PicList 端路径前缀：
siyuan/ - PicList 自定义路径格式：留空
这样上传的图片就全部平铺在siyuan/目录下。加上思源插件那边也配同一个前缀，两边就对齐了。
3.3 测试上传
配置完成后，回到 PicList 主界面，随便拖一张图进去，看看返回的 URL 是否正常。正常情况下上传成功后，右侧会显示一个 URL 链接。这一步能成功，说明 PicList 这边问题不大。
如果返回错误，优先检查自定义节点格式和区域代码是否匹配，这两个是 S3 签名计算的关键参数。
4. 思源笔记 S3 插件配置
4.1 安装并启用插件
在思源笔记的设置里，打开“集市”，找到 S3 插件，点击安装。装完在“已下载”里启用它，然后进入插件设置面板。
不同版本的插件界面可能略有差异，v1.0.2的整体设置项分成了三块：S3 连接配置、路径映射、导出设置。
4.2 连接参数填写
在 S3 连接配置区域，需要填的参数和 PicList 那边是同一套，但有些细微差别：
- Endpoint：这里填协议头和域名，不包含 bucket 名称。如果填错了，插件可能连不上。
- Bucket：填写存储桶名称。
- Region：和 PicList 里保持一致。
- AccessKey 和 SecretKey：也和 PicList 用同一个密钥对。
- Prefix：这里的语义是“所有附件挂载在这个前缀下”，我填的是
siyuan/，和 PicList 那边统一。
填完之后先别急着导出，点一下“测试连接”，确保插件能列出 Bucket 内容。这一步非常有必要，可以提前暴露 Endpoint 或签名问题。
4.3 目录结构与资源文件处理
思源笔记的附件分两块：
- 资产文件（比如
assets/下的图片、PDF）：这类文件在 S3 模式下会被插件自动上传，并在文档里改写引用路径。 - 导出时的临时文件：当你把笔记导出为 Markdown 或 PDF 时，插件会把 S3 上的对应文件拉下来，重新组装成资源文件。
v1.0.2 在导出部分的改进是用“映射表”来管理 S3 路径和本地资源路径之间的对应关系。这个映射表是内存里动态生成的，所以一旦某个文件在 S3 上丢了，导出时图片就会裂。这就要靠 PicList 的相册管理来检查完整性。
5. 手把手实操：完整配置流程
5.1 从零开始的配置步骤
下面是我重新在干净环境里走了一遍的完整流程：
- 创建存储桶：在某云控制台创建
siyuan-assets，地域选ap-southeast-1（新加坡，我服务器在那），权限设为私有。 - 创建子账号并授权：为这个桶单独创建一个子用户，只授予该桶的读写权限。不建议直接用主账号密钥，出了安全问题影响面太大。
- PicList 配置：
- 图床设置 → S3 兼容 → 新建
- 应用 ID：填入子账号 AccessKey
- 应用密钥：填入子账号 SecretKey
- 存储桶：
siyuan-assets - 区域：
ap-southeast-1 - 自定义节点：
https://s3.ap-southeast-1.amazonaws.com - 路径前缀：
siyuan/
- PicList 上传测试：拖一张测试图，确认 URL 能访问（私有桶需要签名 URL 才能访问，这个通过 PicList 内置的预览功能就能验证）。
- 思源 S3 插件配置：
- 启用插件
- S3 连接配置同上，Endpoint 填
https://s3.ap-southeast-1.amazonaws.com - Prefix 填
siyuan/ - 测试连接通过
- 导出验证：打开任意一篇带图片的笔记，选择导出 Markdown，拉下来的压缩包里应该包含图片文件，且相对路径正确。
5.2 关键参数对照表
| 配置项 | PicList | 思源 S3 插件 | 说明 |
|---|---|---|---|
| 节点地址 | 自定义节点 | Endpoint | 协议头要写完整 |
| 空间名 | 存储桶 | Bucket | 必须完全一致 |
| 地域 | 区域 | Region | 签名计算用，不能错 |
| 访问标识 | 应用 ID | AccessKey | 同一个密钥对 |
| 访问密码 | 应用密钥 | SecretKey | 同一个密钥对 |
| 顶层目录 | 路径前缀 | Prefix | 建议都以/结尾 |
5.3 我踩过的坑记录
第一次配置时，我在 PicList 里自定义节点填了带 bucket 的地址（比如https://siyuan-assets.s3.ap-southeast-1.amazonaws.com），而思源插件里却填了不带 bucket 的地址。结果 PicList 上传正常，思源导出却一直报签名错误。原因是 S3 的签名算法中 Host 字段是参与签名的，两边的 Host 不同，服务端校验签名就失败。
建议：无论 PicList 还是思源插件，统一使用不含 bucket 的 endpoint，由客户端自己拼 bucket 路径。这是 S3 兼容性最好的做法，避免服务商额外做路径重写导致签名不一致。
6. 常见问题与排查技巧实录
6.1 连接测试正常，但导出时提示找不到文件
这个问题的根源一般是Prefix 配置不一致或者路径拼接产生双斜杠。
排查方式：
- 在 PicList 相册里点开一张已上传的图片，看它的完整路径是什么。
- 对比思源插件 Prefix 配置，确认能对应上。比如图片路径是
siyuan/2025/01/abc.png，那插件 Prefix 就必须是siyuan/而不是siyuan，否则拼接出来会变成siyuansiyuan/2025/01/abc.png，自然找不到。
6.2 图片能上传，但返回的 URL 无法访问
私有桶的 URL 本来就需要签名参数才能访问，PicList 返回的链接只是一个基础 URL，直接浏览器打开会报AccessDenied。
这个不算问题。如果你希望图片能被公网直接访问，需要：
- 在存储桶设置里开放“只读”权限。
- 或者配置 CDN + 自定义域名回源。
如果只是给自己用，我建议保持私有，配合 PicList 的预览功能就够了。
6.3 导出 Markdown 后，图片在别的电脑上打不开
因为 S3 上的图片虽然可访问，但默认是私有权限，别人拿到你的 Markdown 文件后看不到图。
解决办法：
- 给存储桶绑定自定义域名，并开启公有读（适合博客场景）。
- 或者导出时用插件自带的“下载资源到本地”选项，把图片从 S3 拉回本地打包。
- 或者把 Markdown 发布到支持 S3 协议同步的平台上，比如某些笔记服务商的图床功能。
6.4 插件显示连接超时
这个优先级最高，大概率是网络问题。国内访问海外 S3 节点经常超时，国外访问国内节点同理。
我的建议：
- 先把 Endpoint 在浏览器里访问一下，排除服务商故障。
- 检查防火墙或安全组是否拦截了
443端口出站。 - 如果用了代理，确认代理规则里没有忽略相关域名。部分代理工具会默认绕过非标准端口，导致插件走直连超时。
6.5 PicList 上传慢，但能成功
慢的原因主要是 PicList 默认用的并发数是 3，大文件上传时体现很明显。如果你的网络良好，可以在 PicList 设置里把并发数调到 5 或 8，速度提升立竿见影。
上传时还可以开启“自动重命名”，避免文件名冲突。这个选项在设置里的“上传重命名”区域，选择“时间戳 + 随机字符串”就行。
7. 一些日常使用的体会
插件和 PicList 这套方案跑通之后，日常使用基本不需要再打开 PicList 上传图片了。思源笔记里粘贴截图时，插件会直接走 S3 上传并替换路径，整个过程是无感的。
我这边已经连续用了快一个月，没有出现资源丢失的情况。有一点比较直观的感受是，笔记里图片多了之后，工作空间的体积不再膨胀，本地只留文档结构，所有大文件都在存储桶里，备份和同步都轻松了不少。
一个小技巧：定期在 PicList 相册里按日期筛选，把超过一个月、且笔记里已不引用的图片清理掉。对象存储的存储费用虽然便宜，但长期堆积不用的碎片文件也会造成浪费。配合生命周期规则设置 180 天自动清理，省心很多。
如果你一开始配完发现导出图片裂了，不要急着怀疑插件有问题，先按上面的排查路径走一遍。这个组合看似环节多，但只要端点和前缀对了，后面基本不会再出岔子。
