Images are the part of a website most prone to "getting slower the more you use it": originals that are several MB, list pages loading a dozen images at once, broken thumbnails, and uploads rejected by the server. X1 collects these problems into two settings pages: storage method and image processing. Understand these two first, then talk about CDN.

KingCMS X1 front-end homepage example
The loading speed of front-end images depends on three settings: save location, dimensions, and format.

1. Where images are stored

The admin "Settings → Content & Media → Storage" (/admin/settings/content/storage) determines the save location, and the default is "Local": images are written to data/uploads/year/month/ outside the site root, and the front end accesses them via /media/year/month/.... nginx must point /media/ to data/uploads/ and disable PHP execution in that directory; otherwise images will be run as programs.

Lists and thumbnails go through /img/...; on first access the program generates WebP and stores it in public/img/, after which the web server serves it directly. This directory must be writable, otherwise thumbnails will return 404. When using local storage you can also fill in a CDN prefix (for example https://cdn.example.com); the signed path stays the same, which is good for long-term caching.

The other option is Cloudflare Images: the account ID, account hash, and API key must all have values, otherwise it cannot be saved; after saving, the token is not echoed back, and submitting it blank means keeping the original value. Newly uploaded images are stored in Cloudflare, and the media record keeps the image ID and public URL.

2. Dimensions and format

"Settings → Content & Media → Image Processing" (/admin/settings/content/image) controls resizing and save format. The default values are as follows:

  • Max width and max height: 1024 pixels each; enter 0 for no limit;
  • Output format: WebP; JPEG and PNG are also available;
  • Compression quality: 92 (1–100; PNG uses lossless compression and ignores this);
  • Single file limit: 20 MB.

The resize rule checks width and height separately and scales down proportionally by the smaller ratio, without cropping or enlarging. For example, if the original is 2048×1536 and both max width and max height are 1024, the result is 1024×768. If the original has an alpha channel and the output format is set to JPEG, the program automatically saves it as PNG instead, to avoid transparent areas turning black.

KingCMS X1 product detail page example
Product images and list thumbnails are both generated under the same set of dimension rules; changes take effect for new images.

3. Upload limits

JPG, PNG, and WebP are supported; the file extension must match the actual content, otherwise it is rejected; a single image cannot exceed 40 million pixels. The "single file limit" is an application-layer limit, and PHP's upload_max_filesize, post_max_size, and nginx's client_max_body_size must be no smaller than it; otherwise the request is rejected by the server before it reaches the program.

Images with identical content reuse the existing media record and do not take up extra space; uploading the same image repeatedly will not bloat the disk.

4. Common issues

  1. Broken thumbnails: for local storage, check whether public/img/ is writable; for Cloudflare, check whether flexible variants are enabled, otherwise resized output will fail.
  2. Upload rejected: first check whether the extension matches the content, then whether the pixel count exceeds 40 million or the file exceeds the limit, and finally whether the PHP/nginx limits are smaller than the application settings.
  3. Transparent images turn black: the output format is set to JPEG; change it to WebP or PNG.
  4. Image URLs have a CDN prefix but do not open: the prefix only applies to local storage; confirm that the CDN has been configured to pull from the origin site.

Summary

Image settings come down to three things: where to store them, how much to resize them, and what format to save them in. For local storage, first configure /media/ and public/img/ properly; if you want to use Cloudflare Images, configure the three credentials and flexible variants all at once. Leave the rest to the defaults of 1024/WebP/92, which are enough for most sites.