Django防CSRF：模板与Ajax配置全解析

本文深入剖析 Django 中 CSRF 防护的核心实践痛点：从模板中 `{% csrf_token %}` 失效的根本原因（render 未传 request 导致上下文缺失 token）到 Ajax 请求因未正确携带 `X-CSRFToken` 请求头而频繁 403；明确指出 `@csrf_exempt` 的误用风险，强调 Webhook 等服务端回调应通过签名验证而非禁用 CSRF；并重点警示关键配置陷阱——如 `CSRF_COOKIE_HTTPONLY` 必须为 `False` 才能让前端读取 token，否则 Ajax 全面失效，同时厘清 `CSRF_TRUSTED_ORIGINS`、`CSRF_USE_SESSIONS` 等设置的真实影响与适用边界，直击开发者在真实项目中踩坑最密集的配置盲区与逻辑误区。

CSRF token 模板标签为什么没生效？

根本原因通常是 render 函数没传 request 对象，导致上下文里压根没注入 csrf_token。Django 的 {% csrf_token %} 不是静态字符串，它依赖 request.META['CSRF_COOKIE'] 和中间件生成的 token 值。

• 错误写法：return render(request, 'form.html', {'data': obj}) —— 这没问题；但若用 HttpResponse 直接返回字符串、或漏传 request（比如误用 render_to_string 且没手动加 RequestContext），{% csrf_token %} 就会渲染成空
• 检查方法：查看页面源码，确认是否真有 <input type="hidden" name="csrfmiddlewaretoken" value="...">
• 模板中必须在
  内使用，且不能放在 if 条件外却依赖未初始化的上下文变量（如 {{ form.csrf_token }} 在 form 是 None 时会静默失败）

Ajax 请求怎么带 CSRF token？

Django 默认只校验 POST/PUT/PATCH/DELETE 请求的 token，但 Ajax 默认不发 X-CSRFToken 头，服务端就直接 403 —— 不是因为 token 错，而是压根没收到。

• 前端要读取 cookie 中的 csrftoken 值（注意不是 CSRF_COOKIE 名，实际 cookie 名由 CSRF_COOKIE_NAME 配置，默认是 csrftoken）
• jQuery 用户可统一配置：$.ajaxSetup({beforeSend: (xhr, settings) => {if (!/^(GET|HEAD|OPTIONS|TRACE)$/i.test(settings.type)) {xhr.setRequestHeader('X-CSRFToken', getCookie('csrftoken'));}}});
• 原生 fetch 更推荐在请求头里显式加：headers: {'X-CSRFToken': document.cookie.match(/csrftoken=([^;]+)/)?.[1] || ''}
• 注意：如果用了 CSRF_COOKIE_SECURE=True 或 CSRF_COOKIE_SAMESITE='Strict'，本地开发（HTTP）或跨站调试时 cookie 可能不被发送，导致 token 为空

@csrf_exempt 和 @csrf_protect 怎么选？

别一看到“第三方回调”就无脑加 @csrf_exempt。Django 的 CSRF 防护只针对浏览器发起的请求，而支付网关、Webhook 等服务端到服务端调用本就不带 cookie，自然绕过校验 —— 此时加 @csrf_exempt 反而暴露漏洞面。

• 真正需要 @csrf_exempt 的场景极少：比如你主动提供 API 给其他前端项目调用，且对方无法控制请求头（老旧系统、嵌入式设备等）
• @csrf_protect 是默认行为，显式加它通常没必要；但它能覆盖类视图中个别方法的豁免（比如继承了 View 的类里某个方法被 @csrf_exempt 修饰过，可在类上再用 @method_decorator(csrf_protect) 强制恢复）
• 更安全的做法是：对 Webhook 接口用签名验证（如 HMAC + timestamp），而不是关 CSRF；对内部微服务调用，走内网通信+IP 白名单

CSRF 设置项哪些动不得？

CSRF_COOKIE_HTTPONLY=True 看似增强安全，实则会让 JavaScript 读不到 csrftoken cookie，Ajax 全军覆没。这是最容易被抄错配置坑到的地方。

• 必须保持 CSRF_COOKIE_HTTPONLY=False（默认值），否则前端拿不到 token 值
• CSRF_USE_SESSIONS=True 把 token 存 session 而非 cookie，虽可规避 XSS 泄露风险，但要求用户已登录（session 未创建时会 500），且增加 DB/缓存压力，中小项目没必要
• CSRF_TRUSTED_ORIGINS 必须配全前端域名（含端口，如 'http://localhost:3000'），否则即使 token 正确也会因 Origin 校验失败而 403

CSRF 的关键不在“有没有 token”，而在 token 是否随每次请求可靠传递、且服务端能否准确关联到发起方身份。cookie 设置错一个 flag，整个链路就断了。

终于介绍完啦！小伙伴们，这篇关于《Django防CSRF：模板与Ajax配置全解析》的介绍应该让你收获多多了吧！欢迎大家收藏或分享给更多需要学习的朋友吧~golang学习网公众号也会发布文章相关知识，快来关注吧！