axios 配置默认值详解：axios.defaults、实例默认值与配置合并优先级

axios 配置默认值详解axios.defaults、实例默认值与配置合并优先级【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios本文围绕 axios 的「配置默认值」机制展开如何为全局或单个实例设置baseURL、headers、timeout等默认值以及当多个层级的配置同时存在时axios 究竟按什么顺序合并它们。读完后你可以准确控制每一次请求的最终生效配置并从 lib/core/mergeConfig.js 的源码层面理解 axios 的三层优先级模型。一、全局默认值axios.defaultsaxios 允许你指定一批默认配置这些配置会应用到每一次请求上。你可以为baseURL、headers、timeout以及其他任意配置属性设置默认值。官方文档docs/pages/advanced/config-defaults.md给出的典型用法如下axios.defaults.baseURL https://jsonplaceholder.typicode.com/posts; axios.defaults.headers.common[Authorization] AUTH_TOKEN; axios.defaults.headers.post[Content-Type] application/x-www-form-urlencoded;这段代码做了三件事把全局baseURL指向某个服务之后axios.get(/1)这类相对路径请求都会拼接在该基础地址之后为所有 HTTP 方法追加Authorization请求头只针对POST请求设置Content-Type为表单编码——因为 axios 的头分为common通用与各方法get/post/put/patch/delete等两类方法级别的头只对对应方法生效。安全警示官方文档原文强调全局请求头会发往所有主机。如果你的应用同时与多个域名通信设置axios.defaults.headers.common[Authorization]会把该 token 发送给所有主机包括你可能并不控制的第三方 API。对于需要携带凭据的客户端请使用下文介绍的、带有受控baseURL的自定义实例而不是修改全局默认值。库内置默认值长什么样axios.defaults的初始内容定义在 lib/defaults/index.js理解这些内置值有助于判断没配置时 axios 到底怎么行为属性默认值说明adapter[xhr, http, fetch]适配器候选列表按顺序探测当前环境可用的实现timeout0超时时间毫秒源码注释明确说明设为0表示不创建超时即请求永不超时xsrfCookieNameXSRF-TOKENXSRF 防护读取的 Cookie 名xsrfHeaderNameX-XSRF-TOKEN回写 XSRF token 的请求头名maxContentLength-1下载响应体的最大字节数-1表示不限制maxBodyLength-1上传请求体的最大字节数-1表示不限制validateStatus(status) status 200 status 300默认只有 2xx 状态码才以 Promise 成功结算headers.common.Acceptapplication/json, text/plain, */*全局 Accept 头Content-Type默认为undefined由transformRequest按数据类型动态推断env{ FormData, Blob }按平台浏览器/Node注入的FormData、Blob类引用此外lib/defaults/index.js 通过循环为delete、get、head、post、put、patch、query各方法初始化了空的headers[method]对象这正是上文axios.defaults.headers.post[Content-Type] ...能生效的前提。transformRequest与transformResponse也在该文件中给出默认实现请求侧负责把普通对象按 Content-Type 序列化为 JSON、x-www-form-urlencoded或multipart/form-data响应侧则在responseType json时对字符串响应做JSON.parse并受transitional.silentJSONParsing/forcedJSONParsing两个过渡开关控制过渡默认值见 lib/defaults/transitional.js当前为silentJSONParsing: true、forcedJSONParsing: true。二、实例级默认值axios.create()与instance.defaultsaxios 实例在创建时就被赋予了一组独立的默认值并且之后仍可通过实例的defaults属性覆盖。文档示例如下var instance axios.create({ baseURL: https://jsonplaceholder.typicode.com/posts, timeout: 1000, headers: { Authorization: foobar }, }); instance.defaults.headers.common[Authorization] AUTH_TOKEN;从源码结构看其背后的机制是默认的导出实例由createInstance(defaults)生成其中defaults就是第一节讲的全局默认对象见 lib/axios.jsAxios类构造函数把传入配置直接存为this.defaults见 lib/core/Axios.js因此instance.defaults就是该实例的配置快照随时可读写关键在于instance.create工厂它执行createInstance(mergeConfig(defaultConfig, instanceConfig))lib/axios.js。也就是说基于已有实例再create()出子实例时父实例的默认值已经先与库默认值合并过一次子实例在其上继续叠加自己的配置。这形成了一条清晰的继承链库默认值 → 父实例默认值 → 子实例默认值。实践建议多租户、多网关场景下为每个后端各建一个baseURL受控的实例可参见 docs/pages/advanced/create-an-instance.md把凭据类请求头限制在实例内避免第一节提到的全局头泄漏问题。三、配置合并优先级库默认值 实例默认值 请求配置当多个层级的配置对同一属性给出不同取值时axios 按固定优先级合并先取库默认值再叠加实例默认属性最后取该次请求的配置参数。源码中的落点只有一次调用——_request中的config mergeConfig(this.defaults, config);lib/core/Axios.js其中config1是实例默认值、config2是当次请求配置合并结果即为本次请求的最终配置。文档给出的三步演示非常直观// 1. 用库提供的默认值创建实例此时 timeout 是库默认值 0不超时 const instance axios.create(); // 2. 把该实例的 timeout 默认值改为 2500 毫秒。 // 此后所有走该实例的请求都会等待 2.5 秒才超时 instance.defaults.timeout 2500; // 3. 某次请求单独指定 5000 毫秒。该请求等待 5 秒后超时 instance.get(/longRequest, { timeout: 5000, });同一个timeout三个层级取值依次为0 → 2500 → 5000该次请求最终生效的是5000而后续未显式指定超时的请求则继续沿用实例层的2500。特殊规则data只从请求配置中取值需要特别注意部分选项是请求级的只从当次请求配置中读取不与默认值合并。data就是其中之一——axios 不会从全局或实例默认值继承、深合并请求体。如果所有请求都需要在请求体里携带公共字段正确做法是在请求拦截器或transformRequest中追加见 docs/pages/advanced/transform-data.md 相关说明并且要小心控制作用范围避免把敏感值发送到错误的端点。这一行为在 lib/core/mergeConfig.js 的合并策略表中可以得到直接印证const mergeMap { url: valueFromConfig2, method: valueFromConfig2, data: valueFromConfig2, baseURL: defaultToConfig2, timeout: defaultToConfig2, // ... };mergeConfig 的四种合并策略lib/core/mergeConfig.js 按属性选择四种策略这解释了为什么有的配置会被请求级覆盖、有的却保留默认值valueFromConfig2url、method、data只认请求配置config2。只要请求级传了该字段就直接采用对象则浅拷贝否则最终配置里不出现该属性——这正是data不做默认值继承的实现依据。defaultToConfig2baseURL、timeout、transformRequest、adapter、responseType等大多数常规项优先取请求级取值请求级未定义时才回落到实例/库默认值。第三节的timeout演示走的正是这条路径。mergeDeepProperties默认策略用于上表之外的自定义字段两侧都是普通对象时递归深合并数组则整体替换source.slice()。headers特殊处理请求级与默认级的头对象做**大小写不敏感caseless**的深合并lib/core/mergeConfig.js且AxiosHeaders实例会先展开成普通对象再参与合并保证Authorization与authorization不会各自为政。另外两个实现细节值得注意合并结果基于Object.create(null)的无原型对象创建并显式恢复hasOwnProperty槽位lib/core/mergeConfig.js目的是防止下游读取config.auth、config.baseURL时继承到被污染的Object.prototype值validateStatus使用mergeDirectKeys策略且额外处理了请求级显式传undefined的过渡语义由transitional.validateStatusUndefinedResolves控制见 lib/core/mergeConfig.js避免误删默认判定函数。以上合并行为由 tests/unit/core/mergeConfig.test.js 系统性验证包括合并后结果是全新对象且不共享headers引用、valueFromConfig2Keys只取请求级、defaultToConfig2Keys的回退逻辑以及validateStatus: undefined与validateStatus: null的区分undefined会按过渡开关处理null则原样保留为null。四、小结三层默认值的使用建议库默认值lib/defaults/index.js定义了 axios 的基线行为不超时、2xx 判成功、按 Content-Type 自动序列化等axios.defaults适合真正全局、无凭据风险的设置如统一的baseURL、通用的Accept切记不要把Authorization之类凭据头放进全局headers.common实例默认值axios.createinstance.defaults是承载凭据与多后端隔离的正确位置实例还可继续create()出携带更多叠加配置的子实例请求级配置拥有最高优先级且url、method、data三项永远以请求级为准请求体的公共字段请通过拦截器或transformRequest注入而不是试图写进默认值。所有最终生效的配置都来自一次mergeConfig(this.defaults, config)调用当你遇到为什么我的默认值没生效时回到 lib/core/mergeConfig.js 的mergeMap表核对该属性所属的合并策略即可得到确定答案。【免费下载链接】axiosPromise based HTTP client for the browser and node.js项目地址: https://gitcode.com/GitHub_Trending/ax/axios创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考