Django上线网站静态文件未更新问题求助

嗨，这个静态文件缓存的坑我踩过好多次了！Django其实提供了几种比手动加?version=x更靠谱的方案，既能解决缓存问题，又不用每次改文件都手动改版本号，下面给你详细说：

1. 官方推荐：自动给文件加哈希（ManifestStaticFilesStorage） #

这是最省心的方案，Django会根据文件内容生成唯一哈希值，自动加到文件名后面（比如style.css变成style.abc123def.css）。只要文件内容变了，哈希就变，浏览器会自动请求新文件，根本不用管缓存的事。

配置步骤： #

• 先在settings.py里修改静态文件配置：

STATIC_URL = '/static/'
# 静态文件收集后的存放目录，生产环境必须配置
STATIC_ROOT = BASE_DIR / 'staticfiles'
# 开启哈希存储
STATICFILES_STORAGE = 'django.contrib.staticfiles.storage.ManifestStaticFilesStorage'

• 运行收集静态文件的命令：

python manage.py collectstatic

这一步会把所有app里的静态文件都复制到STATIC_ROOT目录，同时生成带哈希的版本，还会创建一个staticfiles.json来记录原文件名和哈希文件名的映射。

• 模板里正常使用static模板标签就行：

{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}">

Django会自动把它替换成带哈希的路径，比如/static/css/style.abc123def.css。

2. 手动版本号（适合小项目快速迭代） #

如果不想折腾哈希，也可以手动给静态文件加版本参数，而且可以全局统一管理版本号：

• 在settings.py里定义一个版本变量：

STATIC_FILE_VERSION = 'v20240520'

• 模板里调用这个变量：

{% load static %}
<link rel="stylesheet" href="{% static 'css/style.css' %}?version={{ STATIC_FILE_VERSION }}">
<script src="{% static 'js/main.js' %}?version={{ STATIC_FILE_VERSION }}"></script>

每次更新静态文件后，只需要修改STATIC_FILE_VERSION的值就行，比如改成v20240521，所有引用的地方都会自动更新版本号。

3. 配合缓存控制头（强化生产环境缓存策略） #

生产环境里，建议给静态文件设置长缓存过期时间，再配合上面的哈希/版本号方案，既能让浏览器缓存文件提升性能，又能保证更新时用户拿到新文件。

可以通过自定义静态文件视图来设置缓存头：

• 在项目的urls.py里添加：

from django.conf import settings
from django.conf.urls.static import static
from django.contrib.staticfiles.views import serve

def cached_serve(request, path, insecure=False, **kwargs):
    response = serve(request, path, insecure, **kwargs)
    # 设置1年的缓存过期时间，同时标记为不可变（浏览器不会再发验证请求）
    response['Cache-Control'] = 'max-age=31536000, immutable'
    return response

urlpatterns = [
    # 你的其他URL配置
] + static(settings.STATIC_URL, view=cached_serve)

注意：这个必须和哈希/版本号一起用，不然用户浏览器会一直缓存旧文件直到过期。

开发环境小提示 #

如果是开发环境下修改静态文件没生效，大概率是浏览器缓存，按Ctrl+F5强制刷新就行。或者可以在settings.py里保持DEBUG = True，Django默认会禁用静态文件缓存，每次请求都会拉取最新文件。

内容的提问来源于stack exchange，提问作者D.B