Django CSRF AJAX头配置

在Django项目中处理AJAX请求时，CSRF验证失败是开发者最常遇到的报错之一，具体表现为403 Forbidden状态码。问题的根源在于Django的CSRF中间件默认只从Cookie中读取CSRF令牌，而AJAX请求需要显式地在请求头中携带这个令牌。解决这个问题的核心操作分为两步：确保客户端能获取到CSRF令牌，以及确保每个AJAX请求都正确地在HTTP头中发送这个令牌。

Django的CSRF中间件只有在视图函数显式使用了csrf_token模板标签，或者调用了django.views.decorators.csrf.ensure_csrf_cookie装饰器时，才会向客户端发送CSRF Cookie。对于单页面应用或主要通过AJAX交互的页面，如果页面中没有使用{% csrf_token %}标签，浏览器根本收不到名为csrftoken的Cookie，后续所有AJAX请求都会因为缺少令牌而失败。最稳妥的做法是在项目的根URL配置中，专门添加一个确保CSRF Cookie下发的视图，或者在你的主视图上使用ensure_csrf_cookie装饰器。对于完全前后端分离的项目，建议在Django的settings.py中设置CSRF_COOKIE_HTTPONLY = False，这个值默认为False，但如果你之前出于安全考虑将其设为True，需要改回来，否则JavaScript将无法通过document.cookie读取令牌。同时检查CSRF_COOKIE_SAMESITE设置，如果设为Strict，跨站场景下的请求可能不会携带Cookie，对于前后端分离部署在不同域名下的情况，需要设置为Lax或None，当设为None时必须同时设置CSRF_COOKIE_SECURE = True。

获取CSRF令牌的标准做法是编写一个通用的函数从Cookie中解析出csrftoken的值。Django官方文档推荐使用下面的JavaScript工具函数，它通过正则匹配document.cookie字符串来精确提取令牌值。这个函数应当放在项目的公共JavaScript文件中，确保所有页面都能调用。

function getCookie(name) {
    let cookieValue = null;
    if (document.cookie && document.cookie !== '') {
        const cookies = document.cookie.split(';');
        for (let i = 0; i < cookies.length; i++) {
            const cookie = cookies[i].trim();
            if (cookie.substring(0, name.length + 1) === (name + '=')) {
                cookieValue = decodeURIComponent(cookie.substring(name.length + 1));
                break;
            }
        }
    }
    return cookieValue;
}
const csrftoken = getCookie('csrftoken');

这里有一个容易被忽略的细节：Cookie字符串中的令牌值是经过URL编码的，所以需要使用decodeURIComponent进行解码，否则当令牌中包含特殊字符时会导致验证失败。另外，如果你的Django项目设置了CSRF_COOKIE_NAME参数修改了默认的Cookie名称，getCookie函数中的参数需要对应修改。

获取到令牌后，需要让项目中所有的AJAX请求自动在请求头中携带这个令牌。对于使用原生XMLHttpRequest的项目，需要重写其open方法来注入头信息。对于使用Fetch API的项目，则需要封装一个统一的请求函数。实际开发中绝大多数项目会使用Axios或jQuery等库，针对不同库的配置方式各有不同。

如果使用Axios，最简洁的方式是创建实例时通过defaults.headers.common属性全局设置：

import axios from 'axios';
axios.defaults.headers.common['X-CSRFToken'] = csrftoken;

这段代码需要在获取csrftoken变量之后执行，并且要确保在发送任何请求之前完成配置。Axios会自动将这个头应用到所有同源请求和符合CORS规范的跨域请求中。需要注意的是，Axios对于跨域请求默认不会携带自定义头，需要后端在CORS配置中明确允许X-CSRFToken这个请求头。

如果项目使用jQuery的$.ajax方法，可以通过$.ajaxSetup进行全局配置：

$.ajaxSetup({
    beforeSend: function(xhr, settings) {
        if (!(/^http:.*/.test(settings.url) || /^https:.*/.test(settings.url))) {
            xhr.setRequestHeader("X-CSRFToken", csrftoken);
        }
    }
});

jQuery的这个配置中，条件判断的作用是只对同源请求添加CSRF头，避免向外部域名泄露令牌。这个安全实践同样适用于其他库的配置，在设置全局请求头时应当始终检查请求目标是否属于当前域名。

对于使用原生Fetch API的项目，Fetch不支持像Axios那样的全局默认配置，需要手动封装一个请求函数。一个健壮的封装不仅要自动添加CSRF头，还要处理请求方法判断，因为GET、HEAD、OPTIONS等安全方法按照HTTP规范不应该携带CSRF令牌，Django的CSRF中间件也只会对状态改变的方法进行验证。

function fetchWithCSRF(url, options = {}) {
    const method = (options.method || 'GET').toUpperCase();
    const headers = options.headers || {};
    if (!['GET', 'HEAD', 'OPTIONS', 'TRACE'].includes(method)) {
        headers['X-CSRFToken'] = getCookie('csrftoken');
    }
    return fetch(url, {
        ...options,
        headers: headers,
        credentials: 'same-origin'
    });
}

这个封装中同时设置了credentials: 'same-origin'，确保同源请求携带Cookie，这是CSRF验证机制能够工作的基础。如果你的前后端完全同源部署，这个设置可以省略，但显式写明能避免因默认行为差异导致的问题。

CSRF配置不仅是前端的工作，后端的几个设置项直接影响前端配置的成功率。CSRF_HEADER_NAME默认值为HTTP_X_CSRFTOKEN，Django会从请求的META中读取这个键来获取令牌。当使用AJAX发送X-CSRFToken头时，WSGI服务器会自动将其转换为HTTP_X_CSRFTOKEN键。如果你需要自定义头名称，可以修改这个设置，但前端发送请求时也要使用对应的头名称。

CSRF_TRUSTED_ORIGINS设置对于生产环境至关重要。当你的前端部署在不同于后端的域名下时，必须将前端的源地址添加到此列表中。例如前端在https://example.com，后端API在https://api.example.com，就需要在settings.py中添加：

CSRF_TRUSTED_ORIGINS = [
    'https://example.com',
    'https://www.example.com',
]

这个设置告诉Django信任来自这些源的请求，允许它们通过CSRF验证。注意这里需要包含协议和域名，不能只写域名。对于使用非标准端口的开发环境，端口号也需要包含在内，例如http://localhost:3000。

单页面应用长时间运行后，CSRF令牌可能因为Cookie过期而失效。默认情况下，CSRF Cookie的有效期与浏览器会话一致，关闭浏览器即失效。如果你设置了CSRF_COOKIE_AGE参数延长了Cookie的生命周期，需要注意令牌过期后的处理策略。最佳实践是在AJAX请求的全局错误拦截中检测403状态码，当发现CSRF验证失败时，先尝试刷新页面重新获取令牌，或者引导用户刷新页面。不建议在收到403后通过API动态获取新令牌，因为这样会引入安全风险，攻击者可能利用这个机制绕过CSRF保护。

有些场景下确实需要对特定视图禁用CSRF验证，例如接收第三方Webhook回调的端点。Django提供了csrf_exempt装饰器来实现这一点。但使用豁免时必须确保通过其他方式验证请求来源，比如验证Webhook签名、检查IP白名单等。绝对不要因为调试方便而在开发阶段大量使用csrf_exempt，这会导致上线后遗漏恢复保护。对于基于类的视图，csrf_exempt需要装饰dispatch方法，或者使用method_decorator配合name参数来精确控制豁免的方法。

from django.utils.decorators import method_decorator
from django.views.decorators.csrf import csrf_exempt

@method_decorator(csrf_exempt, name='dispatch')
class WebhookView(View):
    def post(self, request, *args, kwargs):
        # 验证Webhook签名后再处理业务逻辑
        pass

Django采用的CSRF防护策略是双重提交Cookie模式。服务端生成一个随机令牌，一方面通过Cookie发送给客户端，另一方面要求客户端在请求头或POST数据中回传相同的令牌。服务端验证时比对这两个值是否一致。攻击者无法读取跨域Cookie，因此无法伪造正确的令牌值。理解这个原理有助于排查配置问题：如果Cookie中的令牌和请求头中的令牌不匹配，验证就会失败。常见的不匹配原因包括：使用了过期的Cookie、多个标签页使用了不同的令牌、或者前端缓存了旧的令牌值。

配置完成后，通过浏览器开发者工具的网络面板可以直观地验证CSRF头是否被正确添加。发起一个POST类型的AJAX请求，查看请求头中是否包含X-CSRFToken字段，以及请求是否返回了预期的2xx状态码而不是403。还可以在Django的shell中验证令牌的生成和验证逻辑是否正常。如果遇到403错误，首先检查响应体中Django返回的具体错误信息，Django的CSRF失败页面会说明失败原因，例如“CSRF cookie not set”表示Cookie缺失，“CSRF token missing”表示请求头缺失，“CSRF token incorrect”表示令牌值不匹配，根据具体提示对症下药。

配置生效后还需要关注几个安全细节。将CSRF_COOKIE_SECURE设置为True，确保CSRF Cookie只在HTTPS连接下传输。设置CSRF_COOKIE_SAMESITE为Strict或Lax，防止跨站请求携带Cookie。如果你的应用确实需要在跨站场景下工作，使用None值但必须配合Secure标志。定期轮换SECRET_KEY不会影响CSRF令牌的有效性，因为CSRF令牌的生成不依赖SECRET_KEY，而是使用独立的随机值。但如果你使用了基于会话的CSRF存储后端，会话密钥的变更会影响令牌验证。

整个CSRF AJAX头配置的核心链路可以总结为：服务端确保下发Cookie、客户端正确读取Cookie、请求时在头中回传令牌、服务端验证通过。这个链路上的每个环节都有对应的配置项和代码实现，任何一个环节出错都会导致403错误。掌握这个链路后，排查CSRF相关问题就能快速定位到具体环节。