图片处理

PicFast 提供两套图片处理机制，根据场景选择：

  • URL 动态处理 —— 在任意图片 URL 后面追加 @ 加参数即可，结果由 CDN / 浏览器缓存。适合一次性缩放，或同一张源图在多个尺寸场景里复用。
  • 上传时处理 —— 服务端在上传流程里处理并存储结果。适合统一的压缩、剥离元数据、批量水印等"先处理再落盘"的策略。

URL 动态处理（@ 参数）

在图片 URL 后面追加 @ 加逗号分隔的参数；首次处理后会缓存，重复请求直接走缓存。

常用示例

# 原图
https://picfast.example.com/i/abc123.jpg

# 缩放为宽 300px
https://picfast.example.com/i/abc123.jpg@w_300

# 缩放为高 200px
https://picfast.example.com/i/abc123.jpg@h_200

# 适配 300×200 框（保持比例）
https://picfast.example.com/i/abc123.jpg@w_300,h_200

# 压缩到质量 80
https://picfast.example.com/i/abc123.jpg@q_80

# 转换为 WebP
https://picfast.example.com/i/abc123.jpg@f_webp

# 组合使用
https://picfast.example.com/i/abc123.jpg@w_300,h_200,q_60,f_webp

参数

参数说明范围
w_目标宽度（px）1 – 10000
h_目标高度（px）1 – 10000
q_输出质量1 – 100
f_输出格式jpeg、png、webp、gif

行为

  • 同时指定 w_ 和 h_ 时，图片缩放至不超过该框的大小，保持比例（不裁剪）。
  • GIF 不做处理，原样返回。
  • 处理失败时原图原样返回。
  • 处理结果使用 Cache-Control: public, max-age=2592000（30 天），CDN / 浏览器缓存会直接返回处理结果。

上传时处理（服务端）

用户上传图片时，服务端按配置的处理流水线执行一遍，结果直接落盘。原图不再保留。

用户设置

每个用户可在上传页右上角齿轮弹窗里配置自己的处理策略。设置保存在服务器，对之后的所有上传生效。

设置项说明默认值
压缩质量JPEG / WebP 编码质量，1 – 100。仅在输出格式为 jpeg 或 webp 时生效。85
转码格式origin 保持原格式；jpeg / png / webp 转码。origin
去除 EXIF存储前剥离全部 EXIF 元数据（相机、GPS 等）。建议开启以保护隐私。开
文字水印在每张上传图片上叠加可配置文字。下方有详细参数。关

水印参数

选项说明
文本渲染的文字内容。开启水印时必填。
位置top-left、top-right、center、bottom-left、bottom-right。
字号8 – 200（CSS 像素）。
颜色任意 CSS 颜色值（如 #FFFFFF、oklch(...)）。
透明度0 – 1。

管理员控制

管理员可在「访问控制」里配置两个全局开关，覆盖用户设置：

开关作用
allow_user_image_processing关闭时，所有用户都强制使用系统默认处理（质量 85、保持原格式、去 EXIF、无水印）。齿轮弹窗仍可打开但字段禁用。
skip_image_processing开启时，所有上传都跳过处理流水线，文件原样存储。适合做原始备份或内部受信用户场景。

优先级：skip_image_processing > 用户设置；若 skip 关闭且用户未配置，则使用系统默认。

行为

  • 处理在服务端（libvips）一次性完成，存储侧只接收处理后的文件，节省带宽。
  • 原图不保留；如需未处理源文件请自行备份。
  • 每项设置都有服务端校验（质量 1-100、格式枚举、字号 8-200、透明度 0-1），非法值会在保存时返回 400。
  • 处理失败时上传仍成功，使用原图存储（优雅降级）。

存储后端支持

后端URL 动态上传时备注
本地内置内置开箱即用
WebDAV内置内置开箱即用
S3 / OSS / COS / Kodo需要 link_mode: "proxy"内置URL 动态需要 proxy 模式，详见 存储后端

如果云存储后端直接返回 CDN 地址，可以改用云厂商自带的图片处理参数（如阿里云 OSS ?x-oss-process=...、七牛 ?imageView2/...）替代 PicFast 的 URL 动态层。