如何在 Axios 中处理多个 baseURL 而不造成混乱

网罗开发（小红书、快手、视频号同名）

  大家好，我是 展菲，目前在上市企业从事人工智能项目研发管理工作，平时热衷于分享各种编程领域的软硬技能知识以及前沿技术，包括iOS、前端、Harmony OS、Java、Python等方向。在移动端开发、鸿蒙开发、物联网、嵌入式、云原生、开源等领域有深厚造诣。

图书作者：《ESP32-C3 物联网工程开发实战》
图书作者：《SwiftUI 入门，进阶与实战》
超级个体：COC上海社区主理人
特约讲师：大学讲师，谷歌亚马逊分享嘉宾
科技博主：华为HDE/HDG

我的博客内容涵盖广泛，主要分享技术教程、Bug解决方案、开发工具使用、前沿科技资讯、产品评测与使用体验。我特别关注云服务产品评测、AI 产品对比、开发板性能测试以及技术报告，同时也会提供产品优缺点分析、横向对比，并分享技术沙龙与行业大会的参会体验。我的目标是为读者提供有深度、有实用价值的技术洞察与分析。

展菲：您的前沿技术领航员
👋 大家好，我是展菲！
📱 全网搜索“展菲”，即可纵览我在各大平台的知识足迹。
📣 公众号“Swift社区”，每周定时推送干货满满的技术长文，从新兴框架的剖析到运维实战的复盘，助您技术进阶之路畅通无阻。
💬 微信端添加好友“fzhanfei”，与我直接交流，不管是项目瓶颈的求助，还是行业趋势的探讨，随时畅所欲言。
📅 最新动态：2025 年 3 月 17 日
快来加入技术社区，一起挖掘技术的无限潜能，携手迈向数字化新征程！

摘要

许多项目最终需要调用多个后端：一个遗留的单体应用、一个新的微服务，可能还有一个第三方计费 API。它们的 baseURL 不匹配，如果不小心，你的 Axios 配置会变成一堆混乱的导入和复制的拦截器。本文展示了在 Axios 中组织多个 baseURL 的实用、生产级方法——涵盖实例工厂、共享拦截器、动态 baseURL 路由和每个请求的重写——外加一个可运行的演示（Node + Axios），你可以在本地尝试。我们还将深入探讨实际问题，如认证头、重试、取消、类型检查和 CORS。

引言

Axios 很灵活：你可以使用单个全局实例、多个作用域实例，甚至是一个按需生成配置客户端的工厂。"正确"的选择取决于你的仓库规模、服务数量以及它们关注点的差异（认证、超时、头信息）。如果你的团队目前创建一个巨大的 service 并不断动态更改 baseURL，你很快就会遇到问题：重复的拦截器逻辑、混乱的错误处理和难以追踪的 bug。让我们将其转变为清晰且可维护的结构。

多个 baseURL 的处理方案

一个实例，每个请求重写 baseURL

适用于非常小的项目或快速脚本。

import axios from "axios";const http = axios.create({ baseURL: "/api", timeout: 10_000 });// 每个请求重写
http.get("/users", { baseURL: "/server" });
http.post("/answers", { baseURL: "/question" });

优点：简单；拦截器只有一个地方。
缺点：容易忘记重写；关注点混合；更难应用每个服务的默认值（认证、头信息、重试）。

多个实例 + 共享拦截器（你的想法）

是的——这是一个可靠的模式。创建一个小助手来附加拦截器，然后为每个服务创建一个实例。

import axios, { AxiosInstance, InternalAxiosRequestConfig, AxiosError } from "axios";const addInterceptors = (instance: AxiosInstance) => {instance.interceptors.request.use((config: InternalAxiosRequestConfig) => {config.headers.set("X-Trace-Id", crypto.randomUUID());const token = sessionStorage.getItem("token");if (token) config.headers.set("Authorization", `Bearer ${token}`);return config;});instance.interceptors.response.use((res) => res.data, // 解包 .data(err: AxiosError) => {// 标准化错误const status = err.response?.status;const msg = (err.response?.data as any)?.message || err.message;return Promise.reject({ status, message: msg, cause: err });});
};export const serverApi = axios.create({ baseURL: "/server", timeout: 10_000 });
export const questionApi = axios.create({ baseURL: "/question", timeout: 10_000 });
addInterceptors(serverApi);
addInterceptors(questionApi);

优点：清晰的分离；每个服务的默认值；通过助手共享行为。
缺点：如果服务增长，你可能需要更多结构（类型化 SDK、工厂）。

实例工厂 + 服务映射（扩展性好）

当你有许多后端或需要不同的策略（超时、重试）时，从配置生成实例。这避免了到处重复 addInterceptors(...)。

type ServiceKey = "server" | "question" | "billing";const serviceDefs: Record<ServiceKey, { baseURL: string; timeout?: number }> = {server:   { baseURL: "/server",   timeout: 10_000 },question: { baseURL: "/question", timeout: 8_000  },billing:  { baseURL: "https://billing.example.com", timeout: 15_000 }
};import axios, { AxiosInstance } from "axios";const instances = new Map<ServiceKey, AxiosInstance>();const addInterceptors = (ins: AxiosInstance) => {// 同上
};export function getClient(name: ServiceKey): AxiosInstance {if (!instances.has(name)) {const ins = axios.create(serviceDefs[name]);addInterceptors(ins);instances.set(name, ins);}return instances.get(name)!;
}// 用法
const serverApi = getClient("server");
const questionApi = getClient("question");

优点：集中配置；懒创建；易于添加/删除服务；测试变得更简单。
缺点：小的间接层（为了可维护性值得）。

单个实例 + 动态路由器

如果你必须保持单个实例，在请求拦截器中根据请求元数据（例如，自定义头信息或 URL 前缀）路由 baseURL。

const http = axios.create({ baseURL: "/", timeout: 10_000 });http.interceptors.request.use((config) => {const target = (config as any).meta?.service; // 例如 "server" | "question"if (target === "server")   config.baseURL = "/server";if (target === "question") config.baseURL = "/question";return config;
});// 用法
http.get("/users", { meta: { service: "server" } as any });
http.post("/ask", { question: "..." }, { meta: { service: "question" } as any });

优点：一个实例统治所有。
缺点："魔法"元选项可能不透明；类型安全需要额外注意。

可运行的演示（Node + Axios）

我们将构建什么

• 一个小的 Express 服务器，暴露两个具有不同 baseURL 的"服务"：

  • /server/users（用户服务）
  • /question/ask（问答服务）

• 一个 TypeScript 客户端，包含：

  • 实例工厂
  • 共享拦截器
  • 取消 + 重试演示
  • 类型化 API 包装器

服务器（Express）

保存为 server.ts：

import express from "express";const app = express();
app.use(express.json());app.get("/server/users", (_req, res) => {res.json([{ id: 1, name: "Alice" }, { id: 2, name: "Bob" }]);
});app.post("/server/users", (req, res) => {const user = { id: Math.floor(Math.random() * 1000), ...req.body };res.status(201).json(user);
});app.post("/question/ask", (req, res) => {const { question } = req.body;res.json({ answer: `Echo: ${question}`, ts: Date.now() });
});// 模拟慢端点
app.get("/question/slow", async (_req, res) => {await new Promise((r) => setTimeout(r, 5000));res.json({ ok: true });
});const port = 3000;
app.listen(port, () => console.log(`演示服务器在 http://localhost:${port}`));

客户端（带有工厂 + 共享拦截器的 Axios）

保存为 client.ts：

import axios, { AxiosError, AxiosInstance, InternalAxiosRequestConfig } from "axios";// 1) 服务定义
type ServiceKey = "server" | "question";
const serviceDefs: Record<ServiceKey, { baseURL: string; timeout?: number }> = {server:   { baseURL: "http://localhost:3000/server",   timeout: 10_000 },question: { baseURL: "http://localhost:3000/question", timeout: 10_000 },
};// 2) 拦截器（共享）
const addInterceptors = (ins: AxiosInstance) => {ins.interceptors.request.use((config: InternalAxiosRequestConfig) => {config.headers.set("X-Trace-Id", crypto.randomUUID());return config;});ins.interceptors.response.use((res) => res.data,async (error: AxiosError) => {// 在 5xx 错误上简单重试一次const cfg = error.config as any;const status = error.response?.status ?? 0;cfg.__retryCount = cfg.__retryCount || 0;if (status >= 500 && cfg.__retryCount < 1) {cfg.__retryCount++;return ins(cfg);}return Promise.reject(error);});
};// 3) 工厂
const cache = new Map<ServiceKey, AxiosInstance>();
function getClient(name: ServiceKey): AxiosInstance {if (!cache.has(name)) {const ins = axios.create(serviceDefs[name]);addInterceptors(ins);cache.set(name, ins);}return cache.get(name)!;
}// 4) 类型化 API 包装器
type User = { id: number; name: string };
export const UserAPI = {list: () => getClient("server").get<User[]>("/users"),create: (name: string) => getClient("server").post<User>("/users", { name }),
};export const QAAPI = {ask: (q: string) => getClient("question").post<{ answer: string; ts: number }>("/ask", { question: q }),slow: (signal?: AbortSignal) => getClient("question").get<{ ok: boolean }>("/slow", { signal }),
};// 5) 演示运行器
async function main() {console.log("1) 列出用户");console.log(await UserAPI.list());console.log("2) 创建用户");console.log(await UserAPI.create("Charlie"));console.log("3) 提问");console.log(await QAAPI.ask("如何在 Axios 中组织多个 baseURL？"));console.log("4) 取消演示（将在 1 秒时中止慢请求）");const ctrl = new AbortController();const t = setTimeout(() => ctrl.abort("时间预算超出"), 1000);try {console.log(await QAAPI.slow(ctrl.signal));} catch (e: any) {console.log("已取消：", e.message || String(e));} finally {clearTimeout(t);}
}main().catch((e) => {console.error("演示错误：", e?.response?.data || e.message || e);process.exit(1);
});

最小 package.json

{"name": "axios-multi-baseurl-demo","type": "module","scripts": {"dev:server": "tsx server.ts","dev:client": "tsx client.ts"},"dependencies": {"axios": "^1.7.2","express": "^4.19.2"},"devDependencies": {"tsx": "^4.19.1","@types/express": "^4.17.21","typescript": "^5.5.4"}
}

运行方式：

1. npm i
2. npm run dev:server（终端 A）
3. npm run dev:client（终端 B）
   你将看到对 /server 和 /question 的调用，对 5xx 错误的重试（如果有）以及一个取消示例。

为什么这种结构有效

共享行为而不重复

将 addInterceptors 放在一个地方可以保持认证/头信息/日志记录/错误标准化的一致性。如果你的 billing API 需要不同的令牌或 withCredentials，添加第二个助手（addBillingInterceptors）并仅将其应用于该实例。

服务默认值和演进

超时、基本头信息、withCredentials，甚至不同的适配器（Node 与浏览器）可能因服务而异。工厂将这些默认值与服务键绑定，因此未来的更改只需一行配置编辑。

可调试性和类型化

将端点包装在薄类型化助手（UserAPI、QAAPI）后面为你提供：

• 路径和负载类型的自动完成
• 集中式响应解包
• 以后添加每个端点缓存或分页助手的绝佳位置

适用于代理和网关

在浏览器应用中，你通常使用开发代理（Vite/CRA/Next）来重写 /server → http://localhost:3000/server 和 /question → http://localhost:3000/question。相同的实例模式仍然适用，你只需在生产中将 baseURL 切换到相对路径并配置代理。

三个实际场景及示例

微前端命中不同域

你将应用托管在 app.example.com，但调用 user.example.com 和 faq.example.net。使用不同的实例来附加不同的凭据或 CORS 模式。

export const userApi = axios.create({baseURL: "https://user.example.com",withCredentials: true,
});
export const faqApi = axios.create({baseURL: "https://faq.example.net",withCredentials: false,
});
addInterceptors(userApi);
addInterceptors(faqApi);

原因：不同的 cookie/跨域行为不应在服务之间泄漏。

每个服务的重试和退避

计费端点需要健壮的重试；问答服务不需要。拆分拦截器或使用小的重试助手。

function addRetry(ins: AxiosInstance, tries = 3) {ins.interceptors.response.use(undefined, async (err) => {const cfg = err.config || {};cfg.__try = (cfg.__try || 0) + 1;if (cfg.__try < tries && (err.response?.status ?? 0) >= 500) {await new Promise(r => setTimeout(r, 200 * cfg.__try)); // 线性退避return ins(cfg);}return Promise.reject(err);});
}// 仅应用于计费
const billing = axios.create({ baseURL: "https://billing.example.com" });
addInterceptors(billing);
addRetry(billing, 3);

带有 URL 前缀路由的单个实例（网关）

你有一个单一的 API 网关（/api），它转发 /api/server/* 和 /api/question/*。使用一个实例；保持 baseURL 为 /api；通过路径前缀路由，并仍然享受共享逻辑。

const http = axios.create({ baseURL: "/api" });
addInterceptors(http);export const UserAPI = {list: () => http.get("/server/users"),
};
export const QAAPI = {ask: (q: string) => http.post("/question/ask", { question: q }),
};

如果每个调用都通过一个网关域，这很清晰。

常见问题解答

创建多个 Axios 实例昂贵吗？
不。实例是轻量级的。你关心的成本是重复的逻辑——通过共享拦截器/助手或工厂解决。

SSR 或 Node 与浏览器的差异呢？
在 Node 中，Axios 使用 HTTP 适配器；在浏览器中，它使用 XMLHttpRequest/fetch。如果你依赖 cookie，相应地设置 withCredentials 并在服务器上配置 CORS/Set-Cookie。

如何避免令牌在服务之间泄漏？
不要全局附加令牌。在 addInterceptors 中，为正确的实例读取正确的令牌（或使用每个服务的拦截器）。如果服务共享一个令牌，没问题；否则拆分。

我可以在运行时切换 baseURL 吗（例如，基于租户）？
可以。要么在租户更改时构建实例，要么基于租户上下文通过请求拦截器为每个请求重写 config.baseURL。

如何清晰地类型化 config.meta？
通过模块增强扩展 Axios 类型，或定义一个包装器请求函数，该函数接受你自己的类型化选项并将它们合并到 Axios 配置中。

总结

如果你有多个 baseURL，不要与 Axios 对抗——拥抱多个实例。一次性添加共享拦截器，通过一个小工厂连接默认值，并为每个域暴露类型化 API 包装器。对于非常小的项目，每个请求的 baseURL 重写是可以的；对于中型/大型代码库，工厂 + 服务映射模式可以保持整洁和可扩展。包含的 Node 演示为你提供了一个工作的起点：运行它，然后将结构适配到你的项目（超时、头信息、重试、取消、代理）。