axios 请求配置完全指南：从 url 到 maxRate 的配置项详解与源码实现剖析

请求配置（request config）是 axios 中控制一次 HTTP 请求行为的唯一入口，几乎全部能力——URL 拼装、参数序列化、请求体转换、超时取消、代理与重定向、响应校验——都通过它驱动。本文基于当前仓库的官方文档 docs/es/pages/advanced/request-config.md 与对应源码（lib/ 目录）编写，完整覆盖每一个配置项的语义、取值与默认值，并结合源码揭示其底层调用链与安全设计，读完即可在生产环境中精准配置请求并规避常见的安全陷阱。

配置对象总览：唯一的必填项是 url

请求配置用于配置一次请求。可选配置项非常多，但唯一必需的选项是 url；如果配置对象中没有 method 字段，则方法默认为 GET。

在开始逐项讲解前，先记录一条来自官方文档的重要安全提醒：

安全提醒：解压炸弹防护是可选的。 maxContentLength 与 maxBodyLength 的默认值都是 -1（无限制）。一个恶意或被攻陷的服务器可以返回一个很小的 gzip/deflate/brotli/zstd 压缩体，解压后膨胀到数 GB 从而耗尽 Node.js 进程。如果你的请求目标不是完全可信的服务器，务必设置上限：

axios.defaults.maxContentLength = 10 * 1024 * 1024; // 10 MB
axios.defaults.maxBodyLength = 10 * 1024 * 1024;

更多细节参见 安全指南。

这一默认值在源码中可以确认：lib/defaults/index.js 中 maxContentLength: -1、maxBodyLength: -1 是全局默认配置的一部分。

URL 构建：url、baseURL 与 allowAbsoluteUrls

url

url 是请求要访问的地址，可以是字符串，也可以是 URL 实例。

文档同时强调了一条格式规则：http: 或 https: 的 URL 必须在协议后包含 //。像 https:example.com、https:/example.com 这类畸形值会被以 ERR_INVALID_URL 错误拒绝，应使用规范写法 https://example.com。

从源码看，该校验发生在 lib/core/buildFullPath.js 的 assertValidHttpProtocolURL()：正则 malformedHttpProtocol = /^https?:(?!\/\/)/i（第 8 行）检测协议后缺少 // 的字符串，并抛出带 AxiosError.ERR_INVALID_URL 代码的异常。值得注意的是，源码在构造错误信息前会先调用 redactSensitiveURLParts()（第 28-43 行）脱敏 URL 中的 userinfo（凭据）、查询参数值和 fragment，防止秘密随错误日志泄露。

baseURL

baseURL 是拼接到 url 前面的基础 URL，除非 url 本身是绝对 URL。它的价值在于：向同一域名发起请求时无需重复域名、API 前缀或版本号。

文档特别指出：baseURL 只是 URL 构建的便利手段，不是安全边界。如果请求的 url 来自不可信输入，应在传给 axios 前自行校验。相对 url 中可以包含 .. 段，axios 将其与 baseURL 合并后，平台 URL 解析器会规范化路径，可能把请求解析到预期路由前缀之外。allowAbsoluteUrls: false 只能阻止绝对 URL 覆盖 baseURL，并不会校验或限制相对路径。baseURL 同样适用上述“协议后必须有 //”的格式规则。

合并逻辑在 lib/core/buildFullPath.js：

export default function buildFullPath(baseURL, requestedURL, allowAbsoluteUrls, config) {
  assertValidHttpProtocolURL(requestedURL, config);
  let isRelativeUrl = !isAbsoluteURL(requestedURL);
  if (baseURL && (isRelativeUrl || allowAbsoluteUrls === false)) {
    assertValidHttpProtocolURL(baseURL, config);
    return combineURLs(baseURL, requestedURL);
  }
  return requestedURL;
}

allowAbsoluteUrls

allowAbsoluteUrls 决定绝对 URL 是否会覆盖已设置的 baseURL：

• true（默认）：url 为绝对地址时覆盖 baseURL；
• false：url 即使是绝对地址，也会始终被拼接到 baseURL 之后。

method

method 指定请求使用的 HTTP 方法，默认值为 GET。

请求与响应数据转换：transformRequest / transformResponse / parseReviver

transformRequest

transformRequest 允许你在数据发往服务器之前修改它。该函数以请求数据为唯一参数被调用，仅对 PUT、POST、PATCH、DELETE 方法生效。数组中的最后一个函数必须返回字符串、Buffer、ArrayBuffer、FormData 或 Stream 实例。

源码中的默认实现（lib/defaults/index.js）处理了多种分支：HTMLForm 元素会被转换为 FormData；FormData 在 Content-Type 为 JSON 时序列化为 JSON，否则原样通过；Buffer/Stream/File/Blob/ReadableStream 原样返回；URLSearchParams 会强制设置 application/x-www-form-urlencoded;charset=utf-8；普通对象在 application/x-www-form-urlencoded 下走 toURLEncodedForm，在 multipart/form-data 或文件列表场景下走 toFormData（并读取 env.FormData 与 formSerializer 配置），其余对象最终以 application/json 序列化，序列化前后用 stringifySafely() 做往返校验（第 23-36 行）。

transformResponse

transformResponse 允许你在数据进入 then/catch 回调之前修改响应数据，同样以响应数据为唯一参数被调用。默认实现（lib/defaults/index.js）中的关键逻辑：

• Response 或 ReadableStream 直接透传；
• 当（forcedJSONParsing 且未显式设置 responseType）或 responseType === 'json' 时，尝试 JSON.parse；
• 严格模式（silentJSONParsing: false 且 JSONRequested）下，SyntaxError 会被包装为 AxiosError.ERR_BAD_RESPONSE 抛出，其余错误直接抛出；宽松模式则静默保留原始字符串。

parseReviver

parseReviver 让你直接向默认的 transformResponse 内部调用的原生 JSON.parse() 提供一个自定义 "reviver" 函数（源码中即 lib/defaults/index.js 的 JSON.parse(data, own(this, 'parseReviver'))）。它特别适用于高性能的类型水合（例如把 ISO 字符串转换为 Temporal 或 Date 对象），或避免解析过程中的精度丢失。

在现代环境（ES2023+）中，reviver 还能接收第三个参数 context，可以访问原始 JSON 源文本（source），从而实现大整数的精确 BigInt 转换——否则它们会被解析成标准 JS 数字而丢失精度：

const client = axios.create({
  parseReviver: (key, value, context) => {
    // 示例：精度安全的 BigInt 解析
    if (typeof value === 'number' && context?.source) {
      const isInteger = Number.isInteger(value);
      const isUnsafe = !Number.isSafeInteger(value);
      const isValidIntegerString = /^-?\d+$/.test(context.source);

      if (isInteger && isUnsafe && isValidIntegerString) {
        try {
          return BigInt(context.source);
        } catch {
          // 备选：解析失败时返回原值
        }
      }
    }

    // 示例：把日期字符串水合为 Temporal 对象
    if (
      typeof value === 'string' &&
      /^\d{4}-\d{2}-\d{2}$/.test(value) &&
      typeof Temporal !== 'undefined' &&
      Temporal?.PlainDate
    ) {
      return Temporal.PlainDate.from(value);
    }

    return value;
  },
});

注意：Temporal 尚未在所有环境中可用，必要时请考虑使用 polyfill。

查询参数：params 与 paramsSerializer

params

params 是随请求发送的 URL 查询参数，必须是扁平对象或 URLSearchParams 实例。如果 url 中已经包含查询参数，它们会与 params 合并。

paramsSerializer

paramsSerializer 允许你在 params 发往服务器之前自定义序列化方式，支持函数或对象两种形式（对象形式各选项见文末完整示例）。在 TypeScript 中，AxiosRequestConfig<D, P> 使用 P 泛型约束 params，自定义 paramsSerializer 会获得同一类型推导：

interface SearchParams {
  query: string;
  page?: number;
}

const config: AxiosRequestConfig<unknown, SearchParams> = {
  params: { query: "axios", page: 1 },
  paramsSerializer: (params) => `${params.query}:${params.page ?? 1}`,
};

严格 RFC 3986 百分号编码

默认情况下，axios 会把 %3A、%24、%2C、%20 分别解码回 :、$、,、+ 以提升可读性（其中 + 遵循 application/x-www-form-urlencoded 用加号表示空格的惯例）。这些字符在 RFC 3986 的查询组件中都是合法的，因此默认输出是正确的。但部分后端要求严格的百分号编码并会拒绝可读形式，此时可用 encode 选项覆盖默认编码器：

// 按请求设置：查询值输出严格 RFC 3986 百分号编码
axios.get('/foo', {
  params: { filter: JSON.stringify({ startedAt: '2026-01-23' }) },
  paramsSerializer: { encode: encodeURIComponent },
});

// 或者设在实例默认值上
const client = axios.create({
  paramsSerializer: { encode: encodeURIComponent },
});

从源码看，默认编码器正是文档描述的行为——lib/helpers/buildURL.js：

export function encode(val) {
  return encodeURIComponent(val)
    .replace(/%3A/gi, ':')
    .replace(/%24/g, '$')
    .replace(/%2C/gi, ',')
    .replace(/%20/g, '+');
}

buildURL()（同文件第 31-69 行）还负责：函数形式的 paramsSerializer 会被归一化为 { serialize }；encode/serialize 通过 utils.getSafeProp 以原型污染安全的方式读取；序列化结果拼接到 URL 时先剥离已有的 # fragment，再按 ?/& 追加。

请求头与 XSRF 防护

headers

headers 是随请求发送的 HTTP 头，Content-Type 默认为 application/json（由默认 transformRequest 设置，见上文）。

XSRF 三件套：xsrfCookieName、xsrfHeaderName、withXSRFToken

• xsrfCookieName：用作 XSRF token 来源的 cookie 名称。默认值在 lib/defaults/index.js 中为 XSRF-TOKEN；
• xsrfHeaderName：承载 XSRF token 的请求头名称，默认 X-XSRF-TOKEN；
• withXSRFToken：控制 axios 是否读取 XSRF cookie 并在浏览器请求上设置 XSRF 头，接受：
  • undefined（默认）——仅对同源请求设置 XSRF 头；
  • true——始终设置，包括跨源请求；
  • false——从不设置；
  • (config: InternalAxiosRequestConfig) => boolean | undefined——按请求逐个决策的回调。

withXSRFToken: boolean | undefined | ((config: InternalAxiosRequestConfig) => boolean | undefined);

警告：跨源 XSRF 与 withCredentials。 withCredentials 控制跨源请求是否携带凭据（cookie、HTTP 认证）。旧版 axios 中，设置 withCredentials: true 会隐式地让跨源请求携带 XSRF 头；新版 axios 已分离这两个职责：要允许 XSRF 头随跨源请求发送，必须同时设置 withCredentials: true 和 withXSRFToken: true：

axios.get('/user', { withCredentials: true, withXSRFToken: true });

withCredentials

withCredentials 指示跨站（Access-Control）请求是否使用 cookie、Authorization 头或客户端 TLS 证书等凭据。对同源请求，设置它没有效果。

请求体：data 与 formDataHeaderPolicy

data

data 是作为请求体发送的数据，可以是字符串、扁平对象、Buffer、ArrayBuffer、FormData、Stream 或 URLSearchParams，仅对 PUT、POST、DELETE、PATCH 生效。未设置 transformRequest 时，其类型必须属于：

• 字符串、扁平对象、ArrayBuffer、ArrayBufferView、URLSearchParams（通用）；
• 仅浏览器：FormData、File、Blob；
• React Native：FormData；
• 仅 Node.js：Stream、Buffer、FormData（form-data 包）。

对浏览器、Web Worker 和 React Native 的 FormData，不要手动设置 Content-Type，环境会自动附加 multipart boundary。

对于提供 getHeaders() 方法的 Node.js FormData 对象，axios 默认会拷贝其返回的全部请求头以保持 v1 兼容。若该 FormData 是自定义或不完全可信的，请设置 formDataHeaderPolicy: 'content-only'，仅拷贝 Content-Type 与 Content-Length，其余请求头通过 headers 显式定义。

formDataHeaderPolicy（仅 Node.js）

控制 axios 如何拷贝 Node.js FormData#getHeaders() 返回的请求头。默认值 'legacy' 拷贝全部头以保留 v1 行为；'content-only' 仅拷贝 Content-Type 与 Content-Length。

符号（Symbol）键的自定义选项

配置合并过程会保留自身的、可枚举的符号属性。TypeScript 应用可以在 AxiosRequestConfig 上扩展特定的符号键，并在请求拦截器或适配器中从 InternalAxiosRequestConfig 读取该选项。继承的或不可枚举的符号属性不会被拷贝，详见 TypeScript 指南 中"自定义请求配置符号键"一节。

超时、进度与取消：timeout / onUploadProgress / onDownloadProgress / cancelToken / signal

timeout

timeout 是请求过期前的毫秒数；超时后请求被中止。从源码看默认值为 0（不创建超时），见 lib/defaults/index.js。

onUploadProgress / onDownloadProgress

onUploadProgress 与 onDownloadProgress 分别用于监听上传与下载进度，回调收到形如 {loaded, total, progress, bytes, estimated, rate, upload/download} 的进度事件对象。

cancelToken

cancelToken 允许你创建一个取消令牌来取消请求，详见 取消指南。

signal

signal 允许向请求传入一个 AbortSignal 实例，从而使用 AbortController API 取消请求。

从源码看，这两种取消机制在调度边界统一检查——lib/core/dispatchRequest.js 的 throwIfCancellationRequested()：先调用 cancelToken.throwIfRequested()，再检查 config.signal.aborted 是否已抛出 CanceledError；该检查在请求发出前与响应到达后各执行一次。

认证、代理与重定向

auth

auth 表示使用 HTTP Basic 认证并提供凭据。它会设置 Authorization 头，覆盖你通过 headers 自定义的同名头。若省略 auth，Node.js HTTP 适配器与 fetch 适配器可以从请求 URL 中提取 Basic 凭据（如 https://user:[e-mail]，百分号编码的凭据会被解码），且 auth 始终优先于 URL 内嵌凭据。Node.js HTTP 适配器中，Basic 认证在同源重定向上保留，在跨源重定向上被移除。注意此参数仅支持 HTTP Basic；Bearer 等令牌请使用自定义 Authorization 头。

proxy

proxy 定义要使用的代理服务器的 host、port 与 protocol；也可以通过约定俗成的环境变量 http_proxy/https_proxy 配置代理。

• 使用环境变量配置代理时，可用 no_proxy 环境变量（逗号分隔的域名列表）指定不走代理的域名；
• 在支持环境变量原生代理的 Node.js 版本上，当选定的 httpAgent/httpsAgent 启用了 proxyEnv（包括通过 NODE_USE_ENV_PROXY=1、--use-env-proxy 或 NODE_OPTIONS=--use-env-proxy 启动的进程），axios 会把环境变量代理处理委托给 Node；没有 proxyEnv 的自定义代理仍走 axios 的环境代理解析。显式的 proxy 配置始终由 axios 处理；
• false 用于禁用代理（忽略环境变量）；proxy.auth 表示用 HTTP Basic 认证连接代理，会设置 Proxy-Authorization 头并覆盖 headers 中自定义的同名头；代理服务器使用 HTTPS 时，protocol 应设为 https；
• 用户在 headers 中提供的 Host 头在经代理转发时会被保留（对 host/Host/HOST 不区分大小写匹配），用于指向与请求 URL 不同的虚拟主机（例如请求实际到达 127.0.0.1:4000，但代理将其视为 example.com）。未提供 Host 时，axios 按惯例将其设为请求 URL 的 hostname:port；
• 对 https:// 目标，axios 通过代理建立 CONNECT 隧道并与源站做端到端 TLS。Proxy-Authorization 只随 CONNECT 请求发送，不会出现在封装的 TLS 请求中；httpsAgent 的 TLS 选项（ca、cert、key、rejectUnauthorized 等）会被转发到生成的隧道代理，继续作用于与源站的 TLS 连接。若你传入 HttpsProxyAgent，axios 会把隧道完全交给该代理处理。

proxy: {
  protocol: "https",
  host: "127.0.0.1",
  hostname: "localhost", // 若 host 与 hostname 同时定义，hostname 优先
  port: 9000,
  auth: {
    username: "mikeymike",
    password: "rapunz3l"
  }
},

maxRedirects（仅 Node.js）

maxRedirects 定义要跟随的最大重定向次数；设为 0 表示不跟随任何重定向。

sensitiveHeaders（仅 Node.js）

sensitiveHeaders 是一个可选的自定义请求头名称数组（如包含秘密的 X-API-Key），Node.js HTTP 适配器在跟随跨源重定向时会删除这些头；匹配不区分大小写；同源重定向保留这些头；当 maxRedirects 为 0 时 axios 不跟随重定向，sensitiveHeaders 不生效。

axios.get('https://api.example.com/users', {
  headers: { 'X-API-Key': 'secret' },
  sensitiveHeaders: ['X-API-Key'],
});

从源码看，lib/adapters/http.js 对 sensitiveHeaders 做了类型校验（必须是字符串数组，否则抛 ERR_BAD_OPTION_VALUE），去重后挂载到 options.beforeRedirects.sensitiveHeaders 钩子中，在每次重定向前执行。

beforeRedirect

beforeRedirect 允许你在请求被重定向前修改它：调整重定向时的请求选项、检查最后一次响应头，或通过抛错取消请求。若 maxRedirects 为 0，beforeRedirect 不会被使用。

beforeRedirect: (options, { headers }) => {
  if (options.hostname === 'example.com' && options.protocol === 'https:') {
    options.auth = 'user:password';
  }
};

安全警告：重定向中的凭据再注入。 beforeRedirect 钩子在敏感头清理之后执行。follow-redirects 库出于安全考虑会在协议降级（HTTPS → HTTP）时删除凭据；由于 beforeRedirect 在之后运行，未核实目标协议就重新注入凭据可能暴露敏感数据。请仅向可信的 HTTPS 目标重新注入凭据，避免在协议降级重定向中注入。

源码印证了该执行顺序：lib/adapters/http.js 中的 dispatchBeforeRedirect 依次调用 proxy、auth、sensitiveHeaders、config 四个 beforeRedirects 钩子，配置级的 beforeRedirect 正是最后执行的 config 钩子（见第 1037-1039 行）。

Socket、传输与协议（主要面向 Node.js）

socketPath（仅 Node.js）

socketPath 定义用于替代 TCP 连接的 UNIX socket，例如用 /var/run/docker.sock 与 Docker 守护进程通信。socketPath 与 proxy 只能指定其一；若同时指定，使用 socketPath。

安全警告。 设置 socketPath 后，URL 中的 hostname 与端口会被忽略，axios 直接与指定 Unix socket 通信。如果请求配置的任何部分来自用户输入（例如转发选项的代理或 webhook 处理器），攻击者可能注入 socketPath 将流量重定向到 /var/run/docker.sock、/run/containerd/containerd.sock、/run/systemd/private 等特权本地 socket，从而完全绕过基于 hostname 的 SSRF 防护（CWE-918）。应过滤来自不可信输入的配置，和/或用 allowedSocketPaths 限制可接受的 socket 路径（见下）。

allowedSocketPaths（仅 Node.js）

限制通过 socketPath 可使用的 socket 路径，接受字符串或字符串数组。定义后，axios 会解析 socketPath 并逐一与（同样被解析的）列表条目比较；不匹配时请求以 ERR_BAD_OPTION_VALUE 代码的 AxiosError 被拒绝。未定义时（默认）socketPath 行为不变。

const client = axios.create({
  allowedSocketPaths: ['/var/run/docker.sock'],
});

// 允许
await client.get('http://localhost/v1.45/info', { socketPath: '/var/run/docker.sock' });

// 拒绝——不在白名单内
await client.get('http://localhost/pods', { socketPath: '/var/run/kubelet.sock' });

空数组（allowedSocketPaths: []）会阻止所有 socket 路径。源码实现在 lib/adapters/http.js：将 allowedSocketPaths 归一化为数组后比对解析路径，失败即抛出含 "socketPath ... is not permitted by allowedSocketPaths" 的 ERR_BAD_OPTION_VALUE 错误；配置合并策略中 allowedSocketPaths 使用 defaultToConfig2（请求级优先），见 lib/core/mergeConfig.js。

transport

transport 定义请求使用的传输层，便于通过不同协议（如 http2）发起请求。

httpAgent 与 httpsAgent

分别定义在 Node.js 中执行 http 与 https 请求时使用的自定义代理（Agent），可借此添加默认未启用的选项（如 keepAlive）。

insecureHTTPParser

指示是否使用接受非法 HTTP 头的非安全解析器，可与不合规的 HTTP 实现互操作；应避免使用。该选项仅在 Node.js 12.10.0 及以上可用，完整 HTTP 请求选项请参考 Node.js 官方文档。

响应处理：responseType / responseEncoding / maxContentLength / maxBodyLength / validateStatus

responseType

responseType 指示服务器响应的数据类型，可选值：

• arraybuffer
• document
• json
• text
• stream
• blob（仅浏览器）
• formdata（仅 fetch 适配器）

responseEncoding（仅 Node.js）

responseEncoding 指定解码响应使用的编码，支持 ascii、ansi、binary、base64、base64url、hex、latin1、ucs-2/ucs2、utf-8/utf8/UTF8、utf16le 及其大小写变体。

注意：对 responseType 为 stream 的响应或客户端请求，该选项被忽略。

maxContentLength（Node.js HTTP/fetch 适配器）

定义响应体最大字节数。Node.js HTTP 适配器在缓冲与流式响应中均会应用；fetch 适配器在响应长度已声明、响应流可跟踪或响应尺寸可确定时应用。

⚠️ 安全： 默认值 -1（无限制）。无限制响应叠加 gzip/deflate/brotli/zstd 解压会构成解压炸弹拒绝服务攻击。消费不完全可信的服务器时请显式设置上限。

maxBodyLength（Node.js HTTP/fetch 适配器）

定义请求体最大字节数。Node.js HTTP 适配器会应用；fetch 适配器在可确定请求体长度时应用。

redact

redact 是一个可选的配置键名数组，AxiosError 通过 toJSON() 序列化时这些键对应的值会被打码。匹配不区分大小写，并沿序列化后的请求配置递归进行；命中值被替换为 [REDACTED ****]。redact 只影响错误序列化，不会修改请求数据、请求头或原始配置对象。

axios
  .get('/user/12345', {
    headers: { Authorization: 'Bearer token' },
    auth: { username: 'me', password: 'secret' },
    redact: ['authorization', 'password'],
  })
  .catch((error) => {
    console.log(error.toJSON().config);
  });

validateStatus

validateStatus 允许覆盖默认的状态码校验。默认情况下，axios 在状态码不在 200-299 区间时拒绝 Promise；提供自定义函数可覆盖此行为——函数返回 true 表示接受该状态码。

从源码看，判定逻辑在 lib/core/settle.js：!validateStatus || validateStatus(response.status) 为真时 resolve，否则以 ERR_BAD_REQUEST（4xx）或 ERR_BAD_RESPONSE（非 4xx）拒绝。

默认配置函数在 lib/defaults/index.js：

validateStatus: function validateStatus(status) {
  return status >= 200 && status < 300;
}

关于 undefined 的特殊语义：默认情况下，显式的 validateStatus: undefined 因 transitional.validateStatusUndefinedResolves 默认为 true 而保留旧版行为——resolve 所有响应状态。若希望显式 undefined 表现得如同"未设置 validateStatus"（即用配置/默认校验器、默认拒绝非 2xx），将其设为 false：

axios.get('/user/12345', {
  validateStatus: undefined,
  transitional: {
    validateStatusUndefinedResolves: false,
  },
});

validateStatus: null 仍然接受所有响应状态。如果关闭了过渡行为又确实想 resolve 所有状态，请使用 validateStatus: null 或返回 true 的校验器。

进阶能力：decompress / maxRate / env / formSerializer / transitional / adapter

decompress（仅 Node.js）

指示响应数据是否自动解压，默认 true。Node.js HTTP 适配器在当前运行时提供相应 zlib 解压器时支持 gzip、deflate、brotli、zstd。

maxRate（仅 Node.js）

maxRate 定义上传和/或下载的最大带宽（字节/秒）。接受单一数字（对两个方向同时生效）或二元数组 [uploadRate, downloadRate]。例如 100 * 1024 表示 100 KB/s。示例参见 速率限制指南。

env

env 用于设置一些环境选项，例如自动把 payload 序列化为 FormData 时使用的 FormData 类。默认值在 lib/defaults/index.js 中按平台解析（如 window?.FormData || global?.FormData）。

formSerializer

formSerializer 配置扁平对象作为 data 发送时序列化为 multipart/form-data 的方式，可用选项：

• visitor — 对每个值递归调用的自定义访问者函数；
• dots — 使用点号记法代替方括号记法；
• metaTokens — 保留 {} 等特殊键尾缀；
• indexes — 控制数组键的方括号格式（null / false / true）；
• maxDepth（默认 100）— 序列化对象嵌套的最大深度，超出抛出 ERR_FORM_DATA_DEPTH_EXCEEDED 代码的 AxiosError，设为 Infinity 可禁用；
• Blob — 转换 ArrayBuffer 值为规范兼容 FormData 时使用的 Blob 构造函数。

全部细节见 multipart/form-data 格式 与下文完整示例。

transitional

transitional 用于开启或关闭特定的过渡特性，可用选项：

• silentJSONParsing：true（默认）时 axios 静默忽略 JSON 解析错误，解析失败时把 response.data 置为 null；设为 false 则抛出 SyntaxError。

  重要： 该选项仅在 responseType 显式设为 'json' 时生效。responseType 省略时，axios 依赖 forcedJSONParsing 尝试解析，失败则静默返回原始字符串，与该设置无关。要让非法 JSON 抛错，需同时设置 { responseType: 'json', transitional: { silentJSONParsing: false } }。

• forcedJSONParsing：即使 responseType 不是 'json'，也强制 axios 尝试把响应字符串解析为 JSON；
• clarifyTimeoutError：请求超时时细化错误信息，便于排查超时问题；
• validateStatusUndefinedResolves：true（默认）时显式 validateStatus: undefined 为兼容而 resolve 所有状态；false 时把显式 undefined 视同省略，使用配置/默认校验器；
• advertiseZstdAcceptEncoding：true 且当前 Node.js 运行时支持 zstd 解压时，axios 向默认 Accept-Encoding 头追加 zstd；兼容且 decompress 为 true 时 zstd 响应会自动解压；
• legacyInterceptorReqResOrdering：true 时使用旧版的请求/响应拦截器执行顺序。

默认值可在 lib/defaults/transitional.js 中核对：

export default {
  silentJSONParsing: true,
  forcedJSONParsing: true,
  clarifyTimeoutError: false,
  legacyInterceptorReqResOrdering: true,
  advertiseZstdAcceptEncoding: false,
  validateStatusUndefinedResolves: true,
};

adapter

adapter 允许自定义请求处理，便于测试。它返回 Promise 并提供有效响应，详见 适配器指南。内置适配器完整列表：fetch、http、xhr；默认情况下 Node.js 使用 http、浏览器使用 xhr。

源码印证：默认配置为 adapter: ['xhr', 'http', 'fetch']（lib/defaults/index.js），lib/adapters/adapters.js 中 knownAdapters 注册了三个内置适配器，getAdapter()（第 65-115 行）按数组顺序逐个探测，返回第一个与当前环境兼容的适配器；全部不兼容时抛出 ERR_NOT_SUPPORT 并附带每个适配器的拒绝原因。你也可以直接传入适配器数组——axios 会采用其中第一个与当前环境兼容的。

完整请求配置示例

以下示例继承自官方文档，汇总了本页全部配置项（注意：data 是请求级专属字段，axios 不会从默认配置继承或深度合并它；要往请求体注入共享字段，请使用请求拦截器或 transformRequest）：

{
  url: "/posts",
  method: "get",
  baseURL: "https://jsonplaceholder.typicode.com",
  allowAbsoluteUrls: true,
  transformRequest: [function (data, headers) {
    return data;
  }],
  transformResponse: [function (data) {
    return data;
  }],
  headers: {"X-Requested-With": "XMLHttpRequest"},
  params: {
    postId: 5
  },
  paramsSerializer: {
    // 自定义编码函数，以迭代方式发送键值对
    encode?: (param: string): string => { /* 在此执行自定义操作并返回转换后的字符串 */ },

    // 针对整个参数对象的自定义序列化函数，可模拟 1.x 之前的行为
    serialize?: (params: Record<string, any>, options?: ParamsSerializerOptions),

    // 参数中数组索引的格式化配置，三种取值：
    // (1) indexes: null —— 不带方括号
    // (2) indexes: false（默认）—— 空方括号
    // (3) indexes: true —— 带索引的方括号
    indexes: false,

    // 序列化 params 时对象嵌套的最大深度，超出抛出 AxiosError
    // (ERR_FORM_DATA_DEPTH_EXCEEDED)。默认 100，设为 Infinity 禁用。
    maxDepth: 100
  },
  data: {
    firstName: "Fred"
  },
  // 另一种语法：POST 时只发送值的键
  data: "Country=Brasil&City=Belo Horizonte",
  formDataHeaderPolicy: "legacy",
  timeout: 1000,
  withCredentials: false,
  adapter: function (config) {
    // 可任意自定义
  },
  adapter: "xhr",
  auth: {
    username: "janedoe",
    password: "s00pers3cret"
  },
  responseType: "json",
  responseEncoding: "utf8",
  xsrfCookieName: "XSRF-TOKEN",
  xsrfHeaderName: "X-XSRF-TOKEN",
  withXSRFToken: boolean | undefined | ((config: InternalAxiosRequestConfig) => boolean | undefined),
  onUploadProgress: function ({loaded, total, progress, bytes, estimated, rate, upload = true}) {
    // 对 axios 进度事件做任意处理
  },
  onDownloadProgress: function ({loaded, total, progress, bytes, estimated, rate, download = true}) {
    // 对 axios 进度事件做任意处理
  },
  maxContentLength: 2000,
  maxBodyLength: 2000,
  redact: ['authorization', 'password'],
  validateStatus: function (status) {
    return status >= 200 && status < 300;
  },
  maxRedirects: 21,
  sensitiveHeaders: ['X-API-Key'],
  beforeRedirect: (options, { headers }) => {
    if (options.hostname === "typicode.com") {
      options.auth = "user:password";
    }
  },
  socketPath: null,
  allowedSocketPaths: null,
  transport: undefined,
  httpAgent: new http.Agent({ keepAlive: true }),
  httpsAgent: new https.Agent({ keepAlive: true }),
  proxy: {
    protocol: "https",
    host: "127.0.0.1",
    // hostname: "127.0.0.1" // 若 host 与 hostname 同时定义，hostname 优先
    port: 9000,
    auth: {
      username: "mikeymike",
      password: "rapunz3l"
    }
  },
  cancelToken: new CancelToken(function (cancel) {
    cancel("Operation has been canceled.");
  }),
  signal: new AbortController().signal,
  decompress: true,
  insecureHTTPParser: undefined,
  transitional: {
    silentJSONParsing: true,
    forcedJSONParsing: true,
    clarifyTimeoutError: false,
    validateStatusUndefinedResolves: true,
    advertiseZstdAcceptEncoding: false,
    legacyInterceptorReqResOrdering: true,
  },
  env: {
    FormData: window?.FormData || global?.FormData
  },
  formSerializer: {
    // 自定义访问者函数，用于序列化表单值
    visitor: (value, key, path, helpers) => {};

    // 使用点号代替方括号格式
    dots: boolean;

    // 保留键名中的 {} 等特殊尾缀
    metaTokens: boolean;

    // 数组索引格式：null 不带方括号 / false 空方括号 / true 带索引方括号
    indexes: boolean;

    // 对象嵌套最大深度，超出抛出 AxiosError (ERR_FORM_DATA_DEPTH_EXCEEDED)，
    // 默认 100，设为 Infinity 禁用
    maxDepth: 100;
  },
  maxRate: [
    100 * 1024, // 100KB/s 上传上限
    100 * 1024  // 100KB/s 下载上限
  ]
}

延伸阅读

• 安全指南：SSRF、解压炸弹等威胁模型细节
• 适配器指南：内置与自定义适配器的完整说明
• 取消指南：CancelToken 与 AbortSignal 用法
• TypeScript 指南：AxiosRequestConfig<D, P> 泛型与符号键扩展
• 速率限制：maxRate 实战示例
• 源码入口：默认配置、请求调度、URL 构建、Node.js HTTP 适配器、状态码结算