django-csp 4.0破坏性变更迁移指南：一条manage.py check命令自动生成新配置

django-csp 4.0破坏性变更迁移指南：一条manage.py check命令自动生成新配置

【免费下载链接】django-cspContent Security Policy for Django.项目地址: https://gitcode.com/gh_mirrors/dj/django-csp

django-csp 是 Django 项目最常用的Content Security Policy（CSP）安全响应头中间件。4.0 版本引入了破坏性变更：原先一堆CSP_前缀的独立配置项全部废弃，改为字典式的CONTENT_SECURITY_POLICY配置。别慌，官方内置了一条python manage.py check命令，能自动识别旧配置并生成新配置模板，跟着本文走，几分钟即可完成迁移。

django-csp 4.0 到底改了什么？

先了解变更全貌，迁移时心里才有数 🧭

变更详情可见 CHANGES.md 的 4.0 章节。

快速上手：3 步完成 django-csp 4.0 升级

第 1 步：升级包

pip install -U django-csp

第 2 步：注册应用

在settings.py的INSTALLED_APPS中加入"csp"。这一步是关键——只有注册应用后，内置的 Django 系统检查（system checks）才会生效。

第 3 步：运行检查命令

python manage.py check

如果项目里还残留旧版CSP_配置，命令会报出一个csp.E001级别的错误，并且直接打印出为你自动生成的新配置草案。

manage.py check 是如何自动生成新配置的

这是 4.0 最贴心的设计。检查逻辑位于 csp/checks.py：

• 维护了一份 30 余项旧配置名清单（CSP_DEFAULT_SRC、CSP_SCRIPT_SRC等）；
• 逐个检测你的settings.py，把命中的旧配置批量翻译成新字典：去掉CSP_前缀、下划线变连字符、全部小写（如CSP_SCRIPT_SRC→script-src）；
• 自动处理细节：CSP_REPORT_PERCENTAGE的百分比换算、CSP_INCLUDE_NONCE_IN转成NONCE哨兵值、CSP_EXCLUDE_URL_PREFIXES的归位等。

举个例子，旧配置：

CSP_DEFAULT_SRC = ["'self'", "*.example.com"] CSP_SCRIPT_SRC = ["'self'", "js.cdn.com/example/"] CSP_IMG_SRC = ["'self'", "data:", "example.com"] CSP_EXCLUDE_URL_PREFIXES = ["/admin"]

manage.py check输出的新配置大致如下：

CONTENT_SECURITY_POLICY = { "EXCLUDE_URL_PREFIXES": ["/admin"], "DIRECTIVES": { "default-src": [SELF, "*.example.com"], "script-src": [SELF, "js.cdn.com/example/"], "img-src": [SELF, "data:", "example.com"], }, }

你只需把这段输出粘贴回settings.py，再把旧的CSP_配置删掉即可。

新旧配置细节对照，这些坑要注意

NONCE 的写法变了

不再单独列出"哪些指令带 nonce"，而是直接把NONCE常量放进对应指令的源列表（常量定义见 csp/constants.py）：

from csp.constants import NONCE, SELF CONTENT_SECURITY_POLICY = { "DIRECTIVES": { "script-src": [SELF, NONCE], }, }

REPORT_PERCENTAGE 改为浮点数

旧值0.1要写成10.0，表示上报 10% 的违规报告。

装饰器同步升级

视图上的@csp、@csp_update、@csp_replace现在接收字典参数，并支持REPORT_ONLY参数；@csp_exempt无论有没有参数都必须加括号。全局搜索这四个装饰器逐个替换即可。

自定义中间件要改子类方法

如果你继承过CSPMiddleware，旧的build_policy/build_policy_ro方法已弃用（4.1 移除），请改为重写get_policy_parts，它会返回一个可修改的PolicyParts数据类而不是最终字符串。

迁移清单：逐条核对

• ✅pip install -U django-csp升级完成
• ✅INSTALLED_APPS已添加"csp"
• ✅manage.py check通过，无csp.E001错误
• ✅ 旧CSP_前缀配置已全部删除
• ✅NONCE、REPORT_PERCENTAGE等细节已按新格式调整
• ✅ 视图装饰器与自定义中间子已更新
• ✅ 生产 + 预发布环境各跑一次python manage.py check

💡 小技巧：建议先配置一个更严格的CONTENT_SECURITY_POLICY_REPORT_ONLY报告策略，观察浏览器上报的违规数据，再逐步收紧强制策略，避免一次性改严导致页面"炸"掉。

完整配置说明见 docs/configuration.rst，官方迁移文档见 docs/migration-guide.rst。按以上步骤操作，django-csp 4.0 的迁移其实就是一条 check 命令的事，升级后你还能顺手用上"强制 + 报告"双策略这一新能力，让站点安全再上一个台阶 🔒

【免费下载链接】django-cspContent Security Policy for Django.项目地址: https://gitcode.com/gh_mirrors/dj/django-csp