图片是网站里最容易“越用越慢”的部分：原图几 MB、列表页一次加载十几张、缩略图裂掉、上传被服务器拒绝。X1 把这些问题收在两个设置页里：存储方式、图片处理。先把这两处看明白，再谈 CDN。

KingCMS X1 前台首页示例
前台图片的加载速度，取决于保存位置、尺寸和格式三项设置。

一、图片存在哪里

后台「设置 → 内容与媒体 → 存储」（/admin/settings/content/storage）决定保存位置，默认是「本地」：图片写到站点根之外的 data/uploads/年/月/，前台通过 /media/年/月/... 访问。nginx 必须把 /media/ 指到 data/uploads/，并关闭该目录下的 PHP 执行，否则图片会被当程序跑。

列表和缩略图走 /img/...，首次访问时由程序生成 WebP，存到 public/img/，之后由 Web 服务器直接提供。这个目录必须可写，否则缩略图会 404。选本地存储时还可以填 CDN 前缀（例如 https://cdn.example.com），签名路径不变，适合长期缓存。

另一种是 Cloudflare Images：账户 ID、账户 Hash、接口密钥三项都必须有值，否则保存不了；保存后令牌不回显，留空提交表示保留原值。新上传的图片会存到 Cloudflare，媒体记录里保存图片 ID 和公开地址。

二、尺寸与格式

「设置 → 内容与媒体 → 图片处理」（/admin/settings/content/image）控制缩放和保存格式，默认值如下：

  • 最大宽度、最大高度：各 1024 像素；填 0 表示不限制；
  • 输出格式：WebP；可选 JPEG、PNG；
  • 压缩质量：92（1–100，PNG 无损压缩，忽略此项）；
  • 单个文件上限：20 MB。

缩放规则是宽度和高度分别判断，按较小的比例等比缩小，不裁剪、不放大。例如原图 2048×1536，最大宽高都是 1024，结果是 1024×768。原图带透明通道、输出格式又选了 JPEG 时，程序会自动改存 PNG，避免透明区域变黑。

KingCMS X1 商品详情页示例
商品图和列表缩略图都按同一套尺寸规则生成，改设置后新图生效。

三、上传限制

支持 JPG、PNG、WebP 三种格式；文件扩展名必须和实际内容一致，否则拒绝；单张图片不能超过 4000 万像素。“单个文件上限”是程序层限制，PHP 的 upload_max_filesize、post_max_size 和 nginx 的 client_max_body_size 必须不小于它，否则请求在到达程序前就被服务器拒了。

相同内容的图片会复用已有媒体记录，不重复占空间；同一张图反复上传不会把磁盘撑大。

四、常见问题

  1. 缩略图裂：本地存储看 public/img/ 是否可写；Cloudflare 看是否开启了 flexible variants，否则按尺寸输出会失败。
  2. 上传被拒：先看扩展名和内容是否一致，再看像素是否超过 4000 万、文件是否超过上限，最后看 PHP/nginx 的限制是否小于程序设置。
  3. 透明图变黑：输出格式选了 JPEG；改成 WebP 或 PNG。
  4. 图片地址带 CDN 前缀但打不开：前缀只对本地存储生效，确认 CDN 已回源到站点。

小结

图片设置就三件事：存哪里、缩到多大、存成什么格式。本地存储先把 /media/ 和 public/img/ 配好；要上 Cloudflare Images 就把三项凭据和 flexible variants 一次配齐。剩下的交给默认的 1024/WebP/92，大多数站点够用。