django 的 collectstatic 不自动更新浏览器缓存，因其默认不启用静态资源指纹（fingerprinting），不改文件名、不嵌入哈希或版本号，导致 url 不变时浏览器复用缓存；官方推荐使用 manifeststaticfilesstorage 生成带哈希的文件名并自动替换模板中的 static 调用。
为什么 collectstatic 不自动更新浏览器缓存？
Django 的 collectstatic 命令只是把静态文件复制到 STATIC_ROOT，它不改文件名、不生成哈希、也不写版本号——浏览器看到的还是 /static/js/app.js，只要 URL 没变，就可能直接读本地缓存，哪怕服务端文件早已更新。
根本原因在于：Django 默认不启用静态资源指纹（fingerprinting），即没有把内容哈希嵌入文件名或查询参数中。
- 开发时用
runserver+DEBUG=True，Django 会跳过缓存头，但上线后完全失效 - 手动加
?v=1.2.3很容易漏改、难维护、无法保证内容变更才更新 - Nginx/Apache 缓存静态文件时，只认路径，不认识 Django 模板里的逻辑
用 ManifestStaticFilesStorage 生成带哈希的文件名
这是 Django 官方推荐的解决方案：它在 collectstatic 阶段重命名文件（如 app.a5f2b7e89d.js），并生成 staticfiles.json 映射表，模板中调用 {% static %} 时自动替换为带哈希的路径。
配置步骤：
- 在
settings.py中设置：STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'
- 确保
STATICFILES_DIRS正确指向源静态目录（不是STATIC_ROOT） - 运行
python manage.py collectstatic --clear（--clear避免旧哈希文件残留） - 模板中继续用
{% static 'js/app.js' %}，Django 自动输出/static/js/app.a5f2b7e89d.js
注意：ManifestStaticFilesStorage 要求所有静态文件必须能被 collectstatic 扫描到；如果 JS 里硬编码了其他静态路径（比如图片 URL），那些不会被重写，得改用 get_static_prefix 或模板变量。
遇到 ValueError: The file 'xxx' could not be found 怎么办？
这是 Manifest 存储最常报的错，本质是「模板引用了某个静态文件，但 collectstatic 没在 STATICFILES_DIRS 或已安装 app 的 static/ 下找到它」。
- 检查路径拼写：模板里写的是
{% static 'css/main.css' %}，但实际文件是main.scss或放在styles/子目录下 - 确认文件没被
.gitignore或STATICFILES_IGNORE_PATTERNS过滤掉 - 如果用了 webpack/vite 构建前端，确保构建产物（如
dist/static/）已加入STATICFILES_DIRS，而不是只靠collectstatic扫 app 目录 - 临时调试可加
python manage.py collectstatic --dry-run --verbosity=2看它到底找了哪些路径
CDN 场景下如何让 {% static %} 输出完整 URL？
当静态资源托管在 CDN（如 Cloudflare、S3）时，{% static %} 默认仍输出相对路径。需要配合 STATIC_URL 和存储后端协同：
- 设
STATIC_URL = 'https://cdn.example.com/static/'（末尾必须有/） - 若用自定义存储（如
storages.backends.s3boto3.S3Boto3Storage），它会自动拼接 CDN 域名；但ManifestStaticFilesStorage是本地文件系统存储，只负责重命名，不负责上传——所以你得额外跑同步脚本或用 CI 把STATIC_ROOT推到 CDN - 关键点：哈希文件名必须在推送到 CDN 前生成，否则 CDN 上的文件名和
staticfiles.json对不上，模板渲染就会 404
真正容易被忽略的是构建顺序：先 collectstatic 生成哈希文件和 manifest，再把整个 STATIC_ROOT 同步到 CDN，中间不能混入任何手动改名或清理操作。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
