必须加 thumbnail_debug = true，否则缩略图生成失败时静默失败，仅显示空白 img 标签；开发阶段需开启以抛出异常，生产环境可关闭。
easy-thumbnails 安装与基础配置为什么必须加 THUMBNAIL_DEBUG = True
不加这行，缩略图生成失败时静默失败，连 404 都不报——你只看到空白 <img> 标签。开发阶段务必在 settings.py 中显式开启调试：
THUMBNAIL_DEBUG = True
它会让 easy-thumbnails 在生成失败时抛出异常（比如 PIL 缺失、源图不存在、权限不足），而不是返回占位图或空路径。生产环境可关掉，但上线前建议先用它跑通全流程。
其他必要配置包括：
-
INSTALLED_APPS中添加'easy_thumbnails' - 确保已安装 Pillow：
pip install Pillow（easy-thumbnails不自动装它） - 媒体文件配置要正确：
MEDIA_URL和MEDIA_ROOT必须匹配实际部署路径，否则thumbnail_url返回的 URL 会 404
模板中用 {% thumbnail %} 标签裁剪图片时，宽高参数顺序不能颠倒
{% thumbnail %} 的语法是 {% thumbnail image "WIDTHxHEIGHT" %}，注意是 先宽后高，不是 CSS 的 height x width 习惯。写成 "200x150" 表示“最大宽度 200px、最大高度 150px”，内部按比例缩放并裁剪（默认裁剪模式为 crop）。
常见错误写法：
-
"150x200"→ 实际得到的是窄高图，和预期布局错位 -
"200x200"却没裁成正方形？因为默认crop模式依赖源图比例；若源图是 4:3，结果仍是 4:3 的 200×150 图，除非加crop="center" - 想强制拉伸填满？别用
crop，改用scale：{% thumbnail image "200x200" scale="1" %} —— 但会变形，慎用
模型字段中预生成缩略图，generate_all_aliases 要手动触发
easy-thumbnails 默认是懒加载：第一次访问缩略图 URL 时才生成文件。如果你希望在上传图片时就生成所有常用尺寸（比如列表页 120×120、详情页 800×600、封面 1920×1080），得在模型保存后调用 generate_all_aliases。
例如：
from easy_thumbnails.files import get_thumbnailer <p>def save(self, *args, *<em>kwargs): super().save(</em>args, **kwargs) if self.avatar: thumbnailer = get_thumbnailer(self.avatar) thumbnailer.generate_all_aliases()</p>
注意两点：
- 该方法只生成
THUMBNAIL_ALIASES中定义的 alias（比如'avatar_small'），不是所有模板里出现过的尺寸 - 它不会覆盖已有缩略图，除非加参数
force=True；但频繁 force 会影响性能，适合初始化或批量迁移场景
自定义缩略图别名时，THUMBNAIL_ALIASES 的嵌套层级容易漏写 '' 键
很多人照文档抄配置，却在 THUMBNAIL_ALIASES 里漏掉最外层空字符串键，导致 alias 不生效：
# ✅ 正确：必须有 '' 作为默认应用范围
THUMBNAIL_ALIASES = {
'': {
'avatar_small': {'size': (120, 120), 'crop': True},
'cover_large': {'size': (1920, 1080), 'crop': 'smart'},
},
}
<h1>❌ 错误：没有 ''，alias 完全不被识别</h1><p>THUMBNAIL_ALIASES = {
'avatar_small': {'size': (120, 120)},
}</p>
这个 '' 表示“全局作用域”，对应 Django 模板中未指定 app_label 的情况。如果用了 {% thumbnail obj.image "avatar_small" %}，就必须靠这个空键才能匹配到定义。
另外，crop='smart' 依赖 scikit-image 或 opencv-python，不装会 fallback 到普通 crop，但控制台会警告——这点常被忽略，直到上线发现人脸总被切掉一半。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
