jQuery的$.ajax方法表面上看是发起异步请求的入口，实际上它内部会把每次请求的选项对象先交给一组预过滤器处理。ajaxPrefilter注册的过滤函数在这个阶段运行，可以在请求真正发出之前统一修改URL、请求头、数据类型等配置。理解这个机制，对维护大型项目的接口层有很大帮助。

接下来从注册方式、执行时机、典型场景和源码实现四个角度展开。

一、ajaxPrefilter的注册方式与执行时机

jQuery暴露了$.ajaxPrefilter方法，可以注册一个或多个预过滤函数。调用形式有两种：$.ajaxPrefilter(function(options, originalOptions, jqXHR){...})或$.ajaxPrefilter(dataType, function(options, originalOptions, jqXHR){...})。第一种不区分dataType，所有请求都会经过该过滤器；第二种只对声明了匹配dataType的请求生效，例如json、jsonp或项目自定义类型。多个过滤器会按照注册顺序依次执行，执行过程是同步的，后面的过滤器能够看到前面过滤器修改后的选项。

需要特别注意的是，ajaxPrefilter的执行时机发生在jQuery应用完ajaxSetup默认参数之后、真正创建XMLHttpRequest对象之前。也就是说，传入过滤器的options已经是合并后的完整选项，包含默认headers、超时时间等字段。而originalOptions则保留用户最初调用$.ajax时传入的原始参数，方便判断本次请求是否显式设置了某些字段。过滤函数不需要返回值就能修改options，因为对象引用会直接传递。

// 注册一个不区分dataType的预过滤器
$.ajaxPrefilter(function(options, originalOptions, jqXHR) {
    // 统一追加请求头
    options.headers = options.headers || {};
    options.headers['X-Requested-With'] = 'XMLHttpRequest';
});

上面这段代码给所有jQuery ajax请求加上了X-Requested-With请求头。过滤器内部不返回任何值，因此不会改变后续流程。如果希望只针对json请求生效，可以写成$.ajaxPrefilter('json', function(options){...})，此时jQuery会检查options.dataTypes数组，只有包含json或*时才会执行。

二、典型场景：统一追加认证头与接口前缀

在实际项目中，后端接口通常要求携带token或签名参数。如果每个$.ajax调用都手动写headers，容易遗漏并且难以维护。利用ajaxPrefilter可以集中处理这类横切逻辑。比如登录后把token存入localStorage，预过滤器在每次请求时读取并注入Authorization头。

此外，接口地址前缀也常常需要统一。开发环境可能请求/api前缀，生产环境请求另一个网关域名。通过ajaxPrefilter根据当前环境动态拼接URL，业务代码里只需要写相对路径即可。

$.ajaxPrefilter(function(options) {
    var token = localStorage.getItem('access_token');
    if (token) {
        options.headers = options.headers || {};
        options.headers['Authorization'] = 'Bearer ' + token;
    }
    // 仅对相对路径拼接接口前缀
    if (options.url && options.url.indexOf('http') !== 0) {
        options.url = '/api' + options.url;
    }
});

这里使用了options.url.indexOf('http')判断是否为绝对地址，避免重复拼接。需要注意的是，options.url可能为undefined，因此先判断存在性。过滤器执行后，最终发出的请求会携带统一认证头和完整URL，业务侧无需关心。

三、与ajaxSetup的差异及常见陷阱

$.ajaxSetup也能修改全局默认配置，但它本质上是把参数合并到默认选项对象上，运行时机在ajaxPrefilter之前，且一旦设置后所有后续请求都会沿用。ajaxPrefilter则是在每次请求时动态执行，能够根据originalOptions或jqXHR状态做出有条件修改。两者配合使用时要清楚执行顺序：先应用ajaxSetup默认参数，再依次执行过滤器。

常见问题是，在过滤器内部再次调用$.ajax会触发新的过滤流程，如果条件没有严格控制，可能导致无限递归。另一个误区是修改options.dataType后并不会自动改变已经匹配过的dataType列表，因此需要利用返回值通知jQuery重新匹配。jQuery预过滤器允许返回一个字符串作为新的dataType，jQuery会将该值插入options.dataTypes头部并重新进入全部过滤器的匹配流程。

// 根据条件动态降级jsonp
$.ajaxPrefilter('json', function(options) {
    if (options.crossDomain && options.url.indexOf('callback=?') !== -1) {
        return 'jsonp';
    }
});

上面的例子中，当请求被判定为跨域且URL带回调参数时，返回jsonp，jQuery会重新按jsonp类型查找并执行对应的预过滤器，从而改变最终的数据类型处理策略。这种返回值机制在实现跨域兼容时非常有用，但也容易因为无限返回新类型导致循环，所以必须确保返回的新类型能最终匹配到不再返回值的过滤器。

四、源码层面的实现逻辑

jQuery内部维护了一个prefilters数组，每次调用$.ajaxPrefilter都会向数组追加一条记录，记录中包含可选的dataType和handler函数。当真正发起请求时，jQuery通过inspectPrefiltersOrTransports函数遍历这个数组，并针对当前请求的dataTypes逐一检查。匹配规则支持精确dataType名称和通配符*，已经执行过的过滤器不会重复执行。

简化后的执行流程可以概括为：取出当前dataType，遍历过滤器数组，如果过滤器dataType与当前dataType一致或为*，则调用handler。如果handler返回字符串，说明需要切换dataType，函数将新类型插入数组头部并递归调用自身，重新开始匹配。这种设计使得过滤器既负责选项修改，也承担dataType转换的职责。

// 简化后的过滤器执行流程
function inspectPrefiltersOrTransports(prefilters, options, originalOptions, jqXHR) {
    var dataType = options.dataTypes[0];
    var inspected = {};
    for (var i = 0; i < prefilters.length; i++) {
        var prefilter = prefilters[i];
        if (inspected[prefilter.dataType] !== true &&
            (prefilter.dataType === dataType || prefilter.dataType === '*')) {
            inspected[prefilter.dataType] = true;
            var result = prefilter.handler(options, originalOptions, jqXHR);
            if (typeof result === 'string') {
                options.dataTypes.unshift(result);
                return inspectPrefiltersOrTransports(prefilters, options, originalOptions, jqXHR);
            }
        }
    }
}

理解这个流程后，就能更从容地设计全局请求管理方案。ajaxPrefilter适合放置需要动态判断的横切逻辑，例如根据token存在性注入认证头、按环境拼接URL、或者针对特定dataType做请求前处理。而纯静态的默认值仍然推荐使用ajaxSetup，这样职责更清晰，也更容易排查问题。

整体来看，ajaxPrefilter是jQuery ajax体系里一个轻量但强大的扩展点。它把全局请求修改从硬编码中解放出来，让接口层逻辑可以集中维护。只要注意执行顺序、递归触发和dataType返回值这三个关键点，就能避免大部分使用陷阱，写出稳定可控的前端请求层。