尧图网页设计 
axios 请求配置完全指南从 url 到 maxRate 的配置项详解与源码实现剖析【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios请求配置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 与 allowAbsoluteUrlsurlurl是请求要访问的地址可以是字符串也可以是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防止秘密随错误日志泄露。baseURLbaseURL是拼接到url前面的基础 URL除非url本身是绝对 URL。它的价值在于向同一域名发起请求时无需重复域名、API 前缀或版本号。文档特别指出baseURL只是 URL 构建的便利手段不是安全边界。如果请求的url来自不可信输入应在传给 axios 前自行校验。相对url中可以包含..段axios 将其与baseURL合并后平台 URL 解析器会规范化路径可能把请求解析到预期路由前缀之外。allowAbsoluteUrls: false只能阻止绝对 URL 覆盖baseURL并不会校验或限制相对路径。baseURL同样适用上述“协议后必须有//”的格式规则。合并逻辑在 lib/core/buildFullPath.jsexport 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; }allowAbsoluteUrlsallowAbsoluteUrls决定绝对 URL 是否会覆盖已设置的baseURLtrue默认url为绝对地址时覆盖baseURLfalseurl即使是绝对地址也会始终被拼接到baseURL之后。methodmethod指定请求使用的 HTTP 方法默认值为GET。请求与响应数据转换transformRequest / transformResponse / parseRevivertransformRequesttransformRequest允许你在数据发往服务器之前修改它。该函数以请求数据为唯一参数被调用仅对PUT、POST、PATCH、DELETE方法生效。数组中的最后一个函数必须返回字符串、Buffer、ArrayBuffer、FormData 或 Stream 实例。源码中的默认实现lib/defaults/index.js处理了多种分支HTMLForm 元素会被转换为FormDataFormData在 Content-Type 为 JSON 时序列化为 JSON否则原样通过Buffer/Stream/File/Blob/ReadableStream 原样返回URLSearchParams会强制设置application/x-www-form-urlencoded;charsetutf-8普通对象在application/x-www-form-urlencoded下走toURLEncodedForm在multipart/form-data或文件列表场景下走toFormData并读取env.FormData与formSerializer配置其余对象最终以application/json序列化序列化前后用stringifySafely()做往返校验第 23-36 行。transformResponsetransformResponse允许你在数据进入then/catch回调之前修改响应数据同样以响应数据为唯一参数被调用。默认实现lib/defaults/index.js中的关键逻辑Response或ReadableStream直接透传当forcedJSONParsing且未显式设置responseType或responseType json时尝试JSON.parse严格模式silentJSONParsing: false且JSONRequested下SyntaxError会被包装为AxiosError.ERR_BAD_RESPONSE抛出其余错误直接抛出宽松模式则静默保留原始字符串。parseReviverparseReviver让你直接向默认的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 与 paramsSerializerparamsparams是随请求发送的 URL 查询参数必须是扁平对象或URLSearchParams实例。如果url中已经包含查询参数它们会与params合并。paramsSerializerparamsSerializer允许你在params发往服务器之前自定义序列化方式支持函数或对象两种形式对象形式各选项见文末完整示例。在 TypeScript 中AxiosRequestConfigD, P使用P泛型约束params自定义paramsSerializer会获得同一类型推导interface SearchParams { query: string; page?: number; } const config: AxiosRequestConfigunknown, 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.jsexport 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 防护headersheaders是随请求发送的 HTTP 头Content-Type默认为application/json由默认transformRequest设置见上文。XSRF 三件套xsrfCookieName、xsrfHeaderName、withXSRFTokenxsrfCookieName用作 XSRF token 来源的 cookie 名称。默认值在 lib/defaults/index.js 中为XSRF-TOKENxsrfHeaderName承载 XSRF token 的请求头名称默认X-XSRF-TOKENwithXSRFToken控制 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: trueaxios.get(/user, { withCredentials: true, withXSRFToken: true });withCredentialswithCredentials指示跨站Access-Control请求是否使用 cookie、Authorization 头或客户端 TLS 证书等凭据。对同源请求设置它没有效果。请求体data 与 formDataHeaderPolicydatadata是作为请求体发送的数据可以是字符串、扁平对象、Buffer、ArrayBuffer、FormData、Stream 或 URLSearchParams仅对PUT、POST、DELETE、PATCH生效。未设置transformRequest时其类型必须属于字符串、扁平对象、ArrayBuffer、ArrayBufferView、URLSearchParams通用仅浏览器FormData、File、BlobReact NativeFormData仅 Node.jsStream、Buffer、FormDataform-data 包。对浏览器、Web Worker 和 React Native 的FormData不要手动设置Content-Type环境会自动附加 multipart boundary。对于提供getHeaders()方法的 Node.jsFormData对象axios 默认会拷贝其返回的全部请求头以保持 v1 兼容。若该FormData是自定义或不完全可信的请设置formDataHeaderPolicy: content-only仅拷贝Content-Type与Content-Length其余请求头通过headers显式定义。formDataHeaderPolicy仅 Node.js控制 axios 如何拷贝 Node.jsFormData#getHeaders()返回的请求头。默认值legacy拷贝全部头以保留 v1 行为content-only仅拷贝Content-Type与Content-Length。符号Symbol键的自定义选项配置合并过程会保留自身的、可枚举的符号属性。TypeScript 应用可以在AxiosRequestConfig上扩展特定的符号键并在请求拦截器或适配器中从InternalAxiosRequestConfig读取该选项。继承的或不可枚举的符号属性不会被拷贝详见 TypeScript 指南 中自定义请求配置符号键一节。超时、进度与取消timeout / onUploadProgress / onDownloadProgress / cancelToken / signaltimeouttimeout是请求过期前的毫秒数超时后请求被中止。从源码看默认值为0不创建超时见 lib/defaults/index.js。onUploadProgress/onDownloadProgressonUploadProgress与onDownloadProgress分别用于监听上传与下载进度回调收到形如{loaded, total, progress, bytes, estimated, rate, upload/download}的进度事件对象。cancelTokencancelToken允许你创建一个取消令牌来取消请求详见 取消指南。signalsignal允许向请求传入一个AbortSignal实例从而使用AbortControllerAPI 取消请求。从源码看这两种取消机制在调度边界统一检查——lib/core/dispatchRequest.js 的throwIfCancellationRequested()先调用cancelToken.throwIfRequested()再检查config.signal.aborted是否已抛出CanceledError该检查在请求发出前与响应到达后各执行一次。认证、代理与重定向authauth表示使用 HTTP Basic 认证并提供凭据。它会设置Authorization头覆盖你通过headers自定义的同名头。若省略authNode.js HTTP 适配器与 fetch 适配器可以从请求 URL 中提取 Basic 凭据如https://user:passexample.com百分号编码的凭据会被解码且auth始终优先于 URL 内嵌凭据。Node.js HTTP 适配器中Basic 认证在同源重定向上保留在跨源重定向上被移除。注意此参数仅支持 HTTP BasicBearer 等令牌请使用自定义Authorization头。proxyproxy定义要使用的代理服务器的 host、port 与 protocol也可以通过约定俗成的环境变量http_proxy/https_proxy配置代理。使用环境变量配置代理时可用no_proxy环境变量逗号分隔的域名列表指定不走代理的域名在支持环境变量原生代理的 Node.js 版本上当选定的httpAgent/httpsAgent启用了proxyEnv包括通过NODE_USE_ENV_PROXY1、--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 连接。若你传入HttpsProxyAgentaxios 会把隧道完全交给该代理处理。proxy: { protocol: https, host: 127.0.0.1, hostname: localhost, // 若 host 与 hostname 同时定义hostname 优先 port: 9000, auth: { username: mikeymike, password: rapunz3l } },maxRedirects仅 Node.jsmaxRedirects定义要跟随的最大重定向次数设为0表示不跟随任何重定向。sensitiveHeaders仅 Node.jssensitiveHeaders是一个可选的自定义请求头名称数组如包含秘密的X-API-KeyNode.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钩子中在每次重定向前执行。beforeRedirectbeforeRedirect允许你在请求被重定向前修改它调整重定向时的请求选项、检查最后一次响应头或通过抛错取消请求。若maxRedirects为0beforeRedirect不会被使用。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.jssocketPath仅 Node.jssocketPath定义用于替代 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。transporttransport定义请求使用的传输层便于通过不同协议如http2发起请求。httpAgent与httpsAgent分别定义在 Node.js 中执行 http 与 https 请求时使用的自定义代理Agent可借此添加默认未启用的选项如keepAlive。insecureHTTPParser指示是否使用接受非法 HTTP 头的非安全解析器可与不合规的 HTTP 实现互操作应避免使用。该选项仅在 Node.js 12.10.0 及以上可用完整 HTTP 请求选项请参考 Node.js 官方文档。响应处理responseType / responseEncoding / maxContentLength / maxBodyLength / validateStatusresponseTyperesponseType指示服务器响应的数据类型可选值arraybufferdocumentjsontextstreamblob仅浏览器formdata仅 fetch 适配器responseEncoding仅 Node.jsresponseEncoding指定解码响应使用的编码支持ascii、ansi、binary、base64、base64url、hex、latin1、ucs-2/ucs2、utf-8/utf8/UTF8、utf16le及其大小写变体。注意对responseType为stream的响应或客户端请求该选项被忽略。maxContentLengthNode.js HTTP/fetch 适配器定义响应体最大字节数。Node.js HTTP 适配器在缓冲与流式响应中均会应用fetch 适配器在响应长度已声明、响应流可跟踪或响应尺寸可确定时应用。⚠️安全默认值-1无限制。无限制响应叠加 gzip/deflate/brotli/zstd 解压会构成解压炸弹拒绝服务攻击。消费不完全可信的服务器时请显式设置上限。maxBodyLengthNode.js HTTP/fetch 适配器定义请求体最大字节数。Node.js HTTP 适配器会应用fetch 适配器在可确定请求体长度时应用。redactredact是一个可选的配置键名数组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); });validateStatusvalidateStatus允许覆盖默认的状态码校验。默认情况下axios 在状态码不在 200-299 区间时拒绝 Promise提供自定义函数可覆盖此行为——函数返回true表示接受该状态码。从源码看判定逻辑在 lib/core/settle.js!validateStatus || validateStatus(response.status)为真时 resolve否则以ERR_BAD_REQUEST4xx或ERR_BAD_RESPONSE非 4xx拒绝。默认配置函数在 lib/defaults/index.jsvalidateStatus: function validateStatus(status) { return status 200 status 300; }关于undefined的特殊语义默认情况下显式的validateStatus: undefined因transitional.validateStatusUndefinedResolves默认为true而保留旧版行为——resolve 所有响应状态。若希望显式undefined表现得如同未设置validateStatus即用配置/默认校验器、默认拒绝非 2xx将其设为falseaxios.get(/user/12345, { validateStatus: undefined, transitional: { validateStatusUndefinedResolves: false, }, });validateStatus: null仍然接受所有响应状态。如果关闭了过渡行为又确实想 resolve 所有状态请使用validateStatus: null或返回true的校验器。进阶能力decompress / maxRate / env / formSerializer / transitional / adapterdecompress仅 Node.js指示响应数据是否自动解压默认true。Node.js HTTP 适配器在当前运行时提供相应 zlib 解压器时支持 gzip、deflate、brotli、zstd。maxRate仅 Node.jsmaxRate定义上传和/或下载的最大带宽字节/秒。接受单一数字对两个方向同时生效或二元数组[uploadRate, downloadRate]。例如100 * 1024表示 100 KB/s。示例参见 速率限制指南。envenv用于设置一些环境选项例如自动把 payload 序列化为FormData时使用的 FormData 类。默认值在 lib/defaults/index.js 中按平台解析如window?.FormData || global?.FormData。formSerializerformSerializer配置扁平对象作为data发送时序列化为multipart/form-data的方式可用选项visitor— 对每个值递归调用的自定义访问者函数dots— 使用点号记法代替方括号记法metaTokens— 保留{}等特殊键尾缀indexes— 控制数组键的方括号格式null/false/truemaxDepth默认100— 序列化对象嵌套的最大深度超出抛出ERR_FORM_DATA_DEPTH_EXCEEDED代码的AxiosError设为Infinity可禁用Blob— 转换 ArrayBuffer 值为规范兼容FormData时使用的 Blob 构造函数。全部细节见 multipart/form-data 格式 与下文完整示例。transitionaltransitional用于开启或关闭特定的过渡特性可用选项silentJSONParsingtrue默认时 axios 静默忽略 JSON 解析错误解析失败时把response.data置为null设为false则抛出SyntaxError。重要该选项仅在responseType显式设为json时生效。responseType省略时axios 依赖forcedJSONParsing尝试解析失败则静默返回原始字符串与该设置无关。要让非法 JSON 抛错需同时设置{ responseType: json, transitional: { silentJSONParsing: false } }。forcedJSONParsing即使responseType不是json也强制 axios 尝试把响应字符串解析为 JSONclarifyTimeoutError请求超时时细化错误信息便于排查超时问题validateStatusUndefinedResolvestrue默认时显式validateStatus: undefined为兼容而 resolve 所有状态false时把显式undefined视同省略使用配置/默认校验器advertiseZstdAcceptEncodingtrue且当前 Node.js 运行时支持 zstd 解压时axios 向默认Accept-Encoding头追加zstd兼容且decompress为true时 zstd 响应会自动解压legacyInterceptorReqResOrderingtrue时使用旧版的请求/响应拦截器执行顺序。默认值可在 lib/defaults/transitional.js 中核对export default { silentJSONParsing: true, forcedJSONParsing: true, clarifyTimeoutError: false, legacyInterceptorReqResOrdering: true, advertiseZstdAcceptEncoding: false, validateStatusUndefinedResolves: true, };adapteradapter允许自定义请求处理便于测试。它返回 Promise 并提供有效响应详见 适配器指南。内置适配器完整列表fetch、http、xhr默认情况下 Node.js 使用http、浏览器使用xhr。源码印证默认配置为adapter: [xhr, http, fetch]lib/defaults/index.jslib/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: Recordstring, 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: CountryBrasilCityBelo 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 指南AxiosRequestConfigD, P泛型与符号键扩展速率限制maxRate实战示例源码入口默认配置、请求调度、URL 构建、Node.js HTTP 适配器、状态码结算【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 axios 请求配置完全指南：从 url 到 maxRate 的配置项详解与源码实现剖析
axios 请求配置完全指南从 url 到 maxRate 的配置项详解与源码实现剖析【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios请求配置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 与 allowAbsoluteUrlsurlurl是请求要访问的地址可以是字符串也可以是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防止秘密随错误日志泄露。baseURLbaseURL是拼接到url前面的基础 URL除非url本身是绝对 URL。它的价值在于向同一域名发起请求时无需重复域名、API 前缀或版本号。文档特别指出baseURL只是 URL 构建的便利手段不是安全边界。如果请求的url来自不可信输入应在传给 axios 前自行校验。相对url中可以包含..段axios 将其与baseURL合并后平台 URL 解析器会规范化路径可能把请求解析到预期路由前缀之外。allowAbsoluteUrls: false只能阻止绝对 URL 覆盖baseURL并不会校验或限制相对路径。baseURL同样适用上述“协议后必须有//”的格式规则。合并逻辑在 lib/core/buildFullPath.jsexport 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; }allowAbsoluteUrlsallowAbsoluteUrls决定绝对 URL 是否会覆盖已设置的baseURLtrue默认url为绝对地址时覆盖baseURLfalseurl即使是绝对地址也会始终被拼接到baseURL之后。methodmethod指定请求使用的 HTTP 方法默认值为GET。请求与响应数据转换transformRequest / transformResponse / parseRevivertransformRequesttransformRequest允许你在数据发往服务器之前修改它。该函数以请求数据为唯一参数被调用仅对PUT、POST、PATCH、DELETE方法生效。数组中的最后一个函数必须返回字符串、Buffer、ArrayBuffer、FormData 或 Stream 实例。源码中的默认实现lib/defaults/index.js处理了多种分支HTMLForm 元素会被转换为FormDataFormData在 Content-Type 为 JSON 时序列化为 JSON否则原样通过Buffer/Stream/File/Blob/ReadableStream 原样返回URLSearchParams会强制设置application/x-www-form-urlencoded;charsetutf-8普通对象在application/x-www-form-urlencoded下走toURLEncodedForm在multipart/form-data或文件列表场景下走toFormData并读取env.FormData与formSerializer配置其余对象最终以application/json序列化序列化前后用stringifySafely()做往返校验第 23-36 行。transformResponsetransformResponse允许你在数据进入then/catch回调之前修改响应数据同样以响应数据为唯一参数被调用。默认实现lib/defaults/index.js中的关键逻辑Response或ReadableStream直接透传当forcedJSONParsing且未显式设置responseType或responseType json时尝试JSON.parse严格模式silentJSONParsing: false且JSONRequested下SyntaxError会被包装为AxiosError.ERR_BAD_RESPONSE抛出其余错误直接抛出宽松模式则静默保留原始字符串。parseReviverparseReviver让你直接向默认的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 与 paramsSerializerparamsparams是随请求发送的 URL 查询参数必须是扁平对象或URLSearchParams实例。如果url中已经包含查询参数它们会与params合并。paramsSerializerparamsSerializer允许你在params发往服务器之前自定义序列化方式支持函数或对象两种形式对象形式各选项见文末完整示例。在 TypeScript 中AxiosRequestConfigD, P使用P泛型约束params自定义paramsSerializer会获得同一类型推导interface SearchParams { query: string; page?: number; } const config: AxiosRequestConfigunknown, 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.jsexport 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 防护headersheaders是随请求发送的 HTTP 头Content-Type默认为application/json由默认transformRequest设置见上文。XSRF 三件套xsrfCookieName、xsrfHeaderName、withXSRFTokenxsrfCookieName用作 XSRF token 来源的 cookie 名称。默认值在 lib/defaults/index.js 中为XSRF-TOKENxsrfHeaderName承载 XSRF token 的请求头名称默认X-XSRF-TOKENwithXSRFToken控制 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: trueaxios.get(/user, { withCredentials: true, withXSRFToken: true });withCredentialswithCredentials指示跨站Access-Control请求是否使用 cookie、Authorization 头或客户端 TLS 证书等凭据。对同源请求设置它没有效果。请求体data 与 formDataHeaderPolicydatadata是作为请求体发送的数据可以是字符串、扁平对象、Buffer、ArrayBuffer、FormData、Stream 或 URLSearchParams仅对PUT、POST、DELETE、PATCH生效。未设置transformRequest时其类型必须属于字符串、扁平对象、ArrayBuffer、ArrayBufferView、URLSearchParams通用仅浏览器FormData、File、BlobReact NativeFormData仅 Node.jsStream、Buffer、FormDataform-data 包。对浏览器、Web Worker 和 React Native 的FormData不要手动设置Content-Type环境会自动附加 multipart boundary。对于提供getHeaders()方法的 Node.jsFormData对象axios 默认会拷贝其返回的全部请求头以保持 v1 兼容。若该FormData是自定义或不完全可信的请设置formDataHeaderPolicy: content-only仅拷贝Content-Type与Content-Length其余请求头通过headers显式定义。formDataHeaderPolicy仅 Node.js控制 axios 如何拷贝 Node.jsFormData#getHeaders()返回的请求头。默认值legacy拷贝全部头以保留 v1 行为content-only仅拷贝Content-Type与Content-Length。符号Symbol键的自定义选项配置合并过程会保留自身的、可枚举的符号属性。TypeScript 应用可以在AxiosRequestConfig上扩展特定的符号键并在请求拦截器或适配器中从InternalAxiosRequestConfig读取该选项。继承的或不可枚举的符号属性不会被拷贝详见 TypeScript 指南 中自定义请求配置符号键一节。超时、进度与取消timeout / onUploadProgress / onDownloadProgress / cancelToken / signaltimeouttimeout是请求过期前的毫秒数超时后请求被中止。从源码看默认值为0不创建超时见 lib/defaults/index.js。onUploadProgress/onDownloadProgressonUploadProgress与onDownloadProgress分别用于监听上传与下载进度回调收到形如{loaded, total, progress, bytes, estimated, rate, upload/download}的进度事件对象。cancelTokencancelToken允许你创建一个取消令牌来取消请求详见 取消指南。signalsignal允许向请求传入一个AbortSignal实例从而使用AbortControllerAPI 取消请求。从源码看这两种取消机制在调度边界统一检查——lib/core/dispatchRequest.js 的throwIfCancellationRequested()先调用cancelToken.throwIfRequested()再检查config.signal.aborted是否已抛出CanceledError该检查在请求发出前与响应到达后各执行一次。认证、代理与重定向authauth表示使用 HTTP Basic 认证并提供凭据。它会设置Authorization头覆盖你通过headers自定义的同名头。若省略authNode.js HTTP 适配器与 fetch 适配器可以从请求 URL 中提取 Basic 凭据如https://user:passexample.com百分号编码的凭据会被解码且auth始终优先于 URL 内嵌凭据。Node.js HTTP 适配器中Basic 认证在同源重定向上保留在跨源重定向上被移除。注意此参数仅支持 HTTP BasicBearer 等令牌请使用自定义Authorization头。proxyproxy定义要使用的代理服务器的 host、port 与 protocol也可以通过约定俗成的环境变量http_proxy/https_proxy配置代理。使用环境变量配置代理时可用no_proxy环境变量逗号分隔的域名列表指定不走代理的域名在支持环境变量原生代理的 Node.js 版本上当选定的httpAgent/httpsAgent启用了proxyEnv包括通过NODE_USE_ENV_PROXY1、--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 连接。若你传入HttpsProxyAgentaxios 会把隧道完全交给该代理处理。proxy: { protocol: https, host: 127.0.0.1, hostname: localhost, // 若 host 与 hostname 同时定义hostname 优先 port: 9000, auth: { username: mikeymike, password: rapunz3l } },maxRedirects仅 Node.jsmaxRedirects定义要跟随的最大重定向次数设为0表示不跟随任何重定向。sensitiveHeaders仅 Node.jssensitiveHeaders是一个可选的自定义请求头名称数组如包含秘密的X-API-KeyNode.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钩子中在每次重定向前执行。beforeRedirectbeforeRedirect允许你在请求被重定向前修改它调整重定向时的请求选项、检查最后一次响应头或通过抛错取消请求。若maxRedirects为0beforeRedirect不会被使用。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.jssocketPath仅 Node.jssocketPath定义用于替代 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。transporttransport定义请求使用的传输层便于通过不同协议如http2发起请求。httpAgent与httpsAgent分别定义在 Node.js 中执行 http 与 https 请求时使用的自定义代理Agent可借此添加默认未启用的选项如keepAlive。insecureHTTPParser指示是否使用接受非法 HTTP 头的非安全解析器可与不合规的 HTTP 实现互操作应避免使用。该选项仅在 Node.js 12.10.0 及以上可用完整 HTTP 请求选项请参考 Node.js 官方文档。响应处理responseType / responseEncoding / maxContentLength / maxBodyLength / validateStatusresponseTyperesponseType指示服务器响应的数据类型可选值arraybufferdocumentjsontextstreamblob仅浏览器formdata仅 fetch 适配器responseEncoding仅 Node.jsresponseEncoding指定解码响应使用的编码支持ascii、ansi、binary、base64、base64url、hex、latin1、ucs-2/ucs2、utf-8/utf8/UTF8、utf16le及其大小写变体。注意对responseType为stream的响应或客户端请求该选项被忽略。maxContentLengthNode.js HTTP/fetch 适配器定义响应体最大字节数。Node.js HTTP 适配器在缓冲与流式响应中均会应用fetch 适配器在响应长度已声明、响应流可跟踪或响应尺寸可确定时应用。⚠️安全默认值-1无限制。无限制响应叠加 gzip/deflate/brotli/zstd 解压会构成解压炸弹拒绝服务攻击。消费不完全可信的服务器时请显式设置上限。maxBodyLengthNode.js HTTP/fetch 适配器定义请求体最大字节数。Node.js HTTP 适配器会应用fetch 适配器在可确定请求体长度时应用。redactredact是一个可选的配置键名数组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); });validateStatusvalidateStatus允许覆盖默认的状态码校验。默认情况下axios 在状态码不在 200-299 区间时拒绝 Promise提供自定义函数可覆盖此行为——函数返回true表示接受该状态码。从源码看判定逻辑在 lib/core/settle.js!validateStatus || validateStatus(response.status)为真时 resolve否则以ERR_BAD_REQUEST4xx或ERR_BAD_RESPONSE非 4xx拒绝。默认配置函数在 lib/defaults/index.jsvalidateStatus: function validateStatus(status) { return status 200 status 300; }关于undefined的特殊语义默认情况下显式的validateStatus: undefined因transitional.validateStatusUndefinedResolves默认为true而保留旧版行为——resolve 所有响应状态。若希望显式undefined表现得如同未设置validateStatus即用配置/默认校验器、默认拒绝非 2xx将其设为falseaxios.get(/user/12345, { validateStatus: undefined, transitional: { validateStatusUndefinedResolves: false, }, });validateStatus: null仍然接受所有响应状态。如果关闭了过渡行为又确实想 resolve 所有状态请使用validateStatus: null或返回true的校验器。进阶能力decompress / maxRate / env / formSerializer / transitional / adapterdecompress仅 Node.js指示响应数据是否自动解压默认true。Node.js HTTP 适配器在当前运行时提供相应 zlib 解压器时支持 gzip、deflate、brotli、zstd。maxRate仅 Node.jsmaxRate定义上传和/或下载的最大带宽字节/秒。接受单一数字对两个方向同时生效或二元数组[uploadRate, downloadRate]。例如100 * 1024表示 100 KB/s。示例参见 速率限制指南。envenv用于设置一些环境选项例如自动把 payload 序列化为FormData时使用的 FormData 类。默认值在 lib/defaults/index.js 中按平台解析如window?.FormData || global?.FormData。formSerializerformSerializer配置扁平对象作为data发送时序列化为multipart/form-data的方式可用选项visitor— 对每个值递归调用的自定义访问者函数dots— 使用点号记法代替方括号记法metaTokens— 保留{}等特殊键尾缀indexes— 控制数组键的方括号格式null/false/truemaxDepth默认100— 序列化对象嵌套的最大深度超出抛出ERR_FORM_DATA_DEPTH_EXCEEDED代码的AxiosError设为Infinity可禁用Blob— 转换 ArrayBuffer 值为规范兼容FormData时使用的 Blob 构造函数。全部细节见 multipart/form-data 格式 与下文完整示例。transitionaltransitional用于开启或关闭特定的过渡特性可用选项silentJSONParsingtrue默认时 axios 静默忽略 JSON 解析错误解析失败时把response.data置为null设为false则抛出SyntaxError。重要该选项仅在responseType显式设为json时生效。responseType省略时axios 依赖forcedJSONParsing尝试解析失败则静默返回原始字符串与该设置无关。要让非法 JSON 抛错需同时设置{ responseType: json, transitional: { silentJSONParsing: false } }。forcedJSONParsing即使responseType不是json也强制 axios 尝试把响应字符串解析为 JSONclarifyTimeoutError请求超时时细化错误信息便于排查超时问题validateStatusUndefinedResolvestrue默认时显式validateStatus: undefined为兼容而 resolve 所有状态false时把显式undefined视同省略使用配置/默认校验器advertiseZstdAcceptEncodingtrue且当前 Node.js 运行时支持 zstd 解压时axios 向默认Accept-Encoding头追加zstd兼容且decompress为true时 zstd 响应会自动解压legacyInterceptorReqResOrderingtrue时使用旧版的请求/响应拦截器执行顺序。默认值可在 lib/defaults/transitional.js 中核对export default { silentJSONParsing: true, forcedJSONParsing: true, clarifyTimeoutError: false, legacyInterceptorReqResOrdering: true, advertiseZstdAcceptEncoding: false, validateStatusUndefinedResolves: true, };adapteradapter允许自定义请求处理便于测试。它返回 Promise 并提供有效响应详见 适配器指南。内置适配器完整列表fetch、http、xhr默认情况下 Node.js 使用http、浏览器使用xhr。源码印证默认配置为adapter: [xhr, http, fetch]lib/defaults/index.jslib/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: Recordstring, 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: CountryBrasilCityBelo 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 指南AxiosRequestConfigD, P泛型与符号键扩展速率限制maxRate实战示例源码入口默认配置、请求调度、URL 构建、Node.js HTTP 适配器、状态码结算【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考