企业官网建设流程全解析

简介：这份PDF面向使用Vue框架开发前端项目、并借助Axios调用后端API的开发者，聚焦请求超时这一常见痛点，给出可落地的处理思路。内容从Axios的基本用法讲起，先通过简单GET请求示例说明then与catch的响应、错误处理流程，再围绕超时场景展开三种方案：一是用axios.defaults.timeout设置默认超时时间；二是借助axios.interceptors请求与响应拦截器捕获错误，识别error.code为ECONNABORTED及timeout提示信息；三是通过retry机制配合retryDelay实现全局超时重发，避免在每个.vue页面重复编写重试逻辑。作者还分析了逐页面重试、请求失效后疯狂刷新等“带坑方案”，并给出基于拦截器的完善写法，帮助读者降低代码耦合、提升程序可靠性与用户体验。资源为1个PDF文件，压缩包约180KB，轻量便携，适合前端初中级开发者随手查阅。目前已有11904人学习下载。

1. 用户点一下查询，转圈转了 30 秒才报 Network Error——问题往往出在没人给 axios 设 timeout

默认情况下，axios.create({ baseURL: '/api' })的timeout是0，含义不是"超时时间为零"，而是"永不超时"。浏览器不会替你兜底，XMLHttpRequest 会一直挂着，直到 TCP 层自己放弃或者用户关掉标签页。于是你看到的现象就是：白屏转圈、按钮禁用、用户以为系统死了，而后端那条慢查询其实在第 40 秒才返回，网关在第 60 秒才断连——前端早就该在 10 秒时给用户一个明确交代了。

这件事在 Vue 项目里格外容易踩，因为很多人把 axios 封装成request.js之后就再没回头看过那个文件。这篇要讲清楚的是：timeout 该配在哪一层、超时错误长什么样（ECONNABORTED和ERR_CANCELED完全不是一回事）、拦到之后怎么提示和重试、并发请求怎么隔离单点超时，最后在 Vue 3 里把这套策略收成一个 composable，业务侧只写一行调用。适合已经用 Vue 做过项目、但超时处理还停留在catch(e => console.log(e))的开发者。

2. axios timeout 的四层配置与超时错误的准确识别

2.1 全局默认、实例默认、单请求覆盖、按接口动态改

axios 的配置是合并式的：先取axios.defaults，再取实例创建时的配置，最后取单次请求config里的值，后者覆盖前者。理解这个优先级，才能决定某个超时值该写在哪。

实践里我一般只在实例上设一个 10 秒的兜底，然后在请求拦截器里按 URL 前缀做一次动态改写。这样业务代码不用记住哪个接口慢，规则集中在一处，新人接手也能一眼看到全貌。

import axios from 'axios' const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE, timeout: 10000, // 实例级兜底：10 秒 }) // 慢接口白名单：命中则放宽到 60 秒 const SLOW_PATHS = [/^\/report\//, /^\/export\//, /^\/sync\//] service.interceptors.request.use((config) => { if (SLOW_PATHS.some((re) => re.test(config.url))) { config.timeout = 60000 } return config }) export default service

这里的逻辑是：axios.create建立了一个独立的实例，不会影响从 CDN 引入的第三方组件内部使用的 axios。拦截器里读取config.url（注意是相对路径，不含 baseURL），命中了就整体抬高阈值。SLOW_PATHS用正则数组而不是字符串数组，是为了兼容/report/2024/summary这种带路径参数的情况——startsWith也能做，但正则更好维护。

2.2 计时器到底在计什么：浏览器和 Node 的语义不一样

这是最容易被忽略的一点。浏览器端 axios 走 XMLHttpRequest，xhr.timeout计的是从send()到readyState === 4的总时长，包含 DNS、TCP 握手、TLS 协商、发送、等待响应、接收响应全过程。也就是说，一个 10 秒的 timeout，在弱网环境下可能握手就花掉了 3 秒，留给服务端的时间只剩 7 秒。

Node 端（比如 Nuxt 的 SSR 阶段、或者用 axios 写脚本）走的是http/https模块，timeout的语义是socket 空闲超时：只要连接上有数据在流动，计时器就会重置。一个持续输出、总耗时 5 分钟但每 100ms 吐一点数据的流式接口，在 Node 端永远不会触发 timeout，在浏览器端却会在 10 秒时准时炸掉。

这个差异导致的典型事故是：本地npm run dev一切正常（浏览器直连），上线后走 SSR 就卡死不返回。排查时要在两端分别确认行为，不能只测一边。

2.3 判断超时别用 message.includes('timeout')

err.message是对外暴露的文本，不同 axios 版本、不同环境措辞不同，用它做判断迟早出问题。可靠的做法是看err.code和err.config。

// utils/error.js export function classifyAxiosError(err) { if (!err || !err.isAxiosError) return 'unknown' // 1. 主动取消：用户切路由、点了取消按钮 if (err.code === 'ERR_CANCELED') return 'canceled' // 2. 超时：浏览器端是 ECONNABORTED，Node 端可能是 ETIMEDOUT if (err.code === 'ECONNABORTED' || err.code === 'ETIMEDOUT') return 'timeout' // 3. 服务器有响应但状态码非 2xx if (err.response) return 'http' // 4. 请求发出去了但拿不到响应：断网、跨域被拦、DNS 失败 if (err.request) return 'network' return 'config' }

关键点是ERR_CANCELED必须排在ECONNABORTED前面单独识别。因为用CancelToken（旧 API）取消请求时，axios 内部抛出的错误历史版本里也带ECONNABORTED，如果混在一起处理，用户主动取消的操作会被误报成"网络超时，请重试"，体验很糟。err.response的存在与否是区分"服务端返回了 4xx/5xx"和"压根没连上"的分水岭，这两个分支的用户提示文案完全不同。

3. 在响应拦截器里做统一兜底与用户提示

3.1 集中处理超时，别让每个组件各写一遍 catch

拦截器是唯一能保证覆盖率的地方。业务组件里写try/catch总会有人漏掉，一旦漏掉就是一个未捕获的 Promise rejection。

import { ElMessage } from 'element-plus' import { classifyAxiosError } from '@/utils/error' service.interceptors.response.use( (res) => { // 业务层约定 code !== 0 视为失败 if (res.data && res.data.code !== 0) { ElMessage.error(res.data.message || '请求失败') return Promise.reject(Object.assign(new Error(res.data.message), { isBizError: true, config: res.config, })) } return res.data.data }, (err) => { const type = classifyAxiosError(err) const url = err.config?.url || '未知接口' if (type === 'timeout') { ElMessage.warning(`「${err.config.meta?.label || url}」响应超时，请稍后重试`) } else if (type === 'canceled') { // 主动取消，静默即可，不要弹窗打扰用户 } else if (type === 'network') { ElMessage.error('网络连接失败，请检查网络后重试') } else if (type === 'http') { const status = err.response.status if (status >= 500) ElMessage.error('服务暂时不可用') else if (status === 404) ElMessage.error('接口不存在') } return Promise.reject(err) } )

第一段成功回调里做业务码判定，把res.data.data直接剥出来，业务层拿到的就是纯数据。第二段失败回调先分类再提示：timeout用warning级别的轻提示（还有救），network用error（用户得自己动手），canceled什么都不做。err.config.meta?.label是一个自定义字段，可以在发请求时塞进去，提示里就能显示"导出报表"而不是/api/report/export这种用户看不懂的路径。

3.2 meta 字段要显式声明默认值，否则 undefined 满天飞

config.meta不是 axios 的标准字段，属于自定义扩展。如果不在创建实例时给它一个默认空对象，上面的可选链虽然不会报错，但你也拿不到任何有用信息。

service.interceptors.request.use((config) => { config.meta = { label: '', silent: false, ...(config.meta || {}) } return config })

silent用来标记"这个请求失败了别弹提示，我自己处理"，比如页面初始化时的探活请求、轮询请求、埋点上报。轮询接口每 5 秒超时一次就弹一次 toast，用户会直接卸载你的应用。

提示：全局提示和silent标记要一起设计。只做全局拦截不做放行开关，后期一定会遇到"某些请求不想弹窗"的需求，那时候再改就要动所有调用点。

3.3 loading 不能一刀切挂在拦截器上

很多人喜欢在请求拦截器里loadingInstance = ElLoading.service()，响应拦截器里 close。这在串行请求场景下会翻车：A 请求发出、B 请求发出、A 返回关掉 loading、B 还在跑但界面已经没有加载态了。正确做法是维护一个计数器，或者干脆把 loading 交给组件自己管。

let pending = 0 let loadingInstance = null function openLoading() { if (pending === 0) loadingInstance = ElLoading.service({ fullscreen: true }) pending++ } function closeLoading() { pending = Math.max(0, pending - 1) if (pending === 0 && loadingInstance) { loadingInstance.close() loadingInstance = null } }

计数器方案是并发安全的：只有从 0 变 1 时才真正挂载遮罩，只有回到 0 时才卸载。Math.max(0, ...)是防御性写法，防止 close 被多调一次导致计数变负、后续请求再也开不了 loading。这个逻辑和超时处理是共生关系——超时请求被 reject 后也要走closeLoading()，否则遮罩会永远留在屏幕上，比不弹提示还糟。

4. 超时之后：取消、重试与并发隔离

4.1 用 AbortController 取消请求，CancelToken 该退休了

Vue 3 项目里切路由时如果不取消上一个页面的在途请求，慢响应回来后会往已经卸载的组件里写数据，轻则警告，重则状态错乱。CancelToken从 axios 0.22 起已被标记废弃，新代码用AbortController。

// composables/useAbortable.js import { onUnmounted } from 'vue' export function useAbortable() { const controllers = new Set() function withSignal(config = {}) { const ctrl = new AbortController() controllers.add(ctrl) return { ...config, signal: ctrl.signal, _ctrl: ctrl } } function abortAll() { controllers.forEach((c) => c.abort()) controllers.clear() } onUnmounted(abortAll) return { withSignal, abortAll } }

AbortController是浏览器原生 API，signal通过config.signal传给 axios。组件卸载时onUnmounted自动触发abortAll，所有在途请求会被中断并抛出code === 'ERR_CANCELED'的错误——这也正是第 2 章里为什么要把canceled单独分类、并且静默处理的原因。用Set而不是数组是为了避免重复加入，同时clear()一次性释放引用，防止内存泄漏。

4.2 幂等请求的超时重试：只重试 GET，且必须退避

超时不等于失败，很多情况下只是瞬时抖动。但重试有两条铁律：只重试幂等请求（GET/HEAD），以及必须用指数退避，否则三个客户端同时超时重试就能把刚恢复的服务再打挂一次。

import axiosRetry from 'axios-retry' axiosRetry(service, { retries: 2, retryDelay: (count) => axiosRetry.exponentialDelay(count), // 约 100ms、200ms shouldResetTimeout: true, // 每次重试重置计时器 retryCondition: (err) => { return ( err.config?.method?.toLowerCase() === 'get' && err.code === 'ECONNABORTED' && !err.config?.meta?.noRetry ) }, onRetry: (count, err, config) => { console.warn(`[retry ${count}] ${config.url}`) }, })

retries: 2意味着最多额外发两次，加上首次共三次。shouldResetTimeout: true很关键：如果不设，重试会共用首次请求的计时器，第一次超时已经耗掉 10 秒，重试还没发出去就被判定超时。retryCondition里卡住 method 是防止 POST 被重试导致重复下单，meta.noRetry是留给业务侧的逃生舱口。onRetry打日志方便线上定位到底是哪几个接口在反复重试。

4.3 并发请求用 allSettled，别让一个超时拖垮整页

首屏经常要并行拉五六个接口。用Promise.all的话，任何一个超时都会让整体 reject，其余四个已经拿到数据的请求结果全被丢掉，用户看到的就是空白页。改用allSettled，配合超时分支的降级展示。

const tasks = [ service.get('/user/profile'), service.get('/notice/list', { timeout: 3000 }), // 次要模块给短超时 service.get('/banner', { meta: { silent: true } }), ] const results = await Promise.allSettled(tasks) const [profile, notice, banner] = results.map((r) => r.status === 'fulfilled' ? r.value : null ) // 关键数据缺失才阻塞，次要数据缺失走占位 if (!profile) { showFullPageError() } else { renderPage({ profile, notice: notice ?? [], banner: banner ?? null }) }

allSettled永远 resolve，所以results里每项自带status字段。这里给通知列表单独设了 3 秒超时，是因为它属于"有就显示、没有就空着"的次要模块，让它拖慢首屏不值得。给 banner 加了silent，失败时不弹提示，用户看到的只是没有横幅，而不是一个刺眼的错误弹窗。映射时用?? []和?? null把 rejected 项统一成可渲染的空值，避免模板里到处写v-if判空。

4.4 大文件上传下载，timeout 要换个思路

timeout是"总时长"还是"空闲时长"，决定了它适不适合用在传输场景。浏览器端是总时长语义，一个 200MB 的文件走 4G 上传，10 秒 timeout 必然失败——哪怕上传进度条一直在动。这类场景不该靠调大 timeout 解决。

把timeout设成0不等于放弃控制，而是把控制权交给进度回调：超过 30 秒loaded没变化，就主动abort()并提示"上传已暂停，请检查网络"。这比等一个 10 分钟的死超时要可靠得多。

5. 把超时策略收成 Vue 3 composable，以及怎么验证它真的生效

5.1 useRequest：业务侧只关心三件事

拦截器解决了"怎么拦"，composable 解决"怎么用"。我习惯让调用方只拿到data、loading、error三样东西，超时被折叠进error.type。

// composables/useRequest.js import { ref, shallowRef } from 'vue' import { classifyAxiosError } from '@/utils/error' export function useRequest(apiFn, { immediate = false, initialData = null } = {}) { const data = shallowRef(initialData) const loading = ref(false) const error = ref(null) // { type: 'timeout' | 'network' | ..., raw } async function run(...args) { loading.value = true error.value = null try { data.value = await apiFn(...args) return data.value } catch (e) { error.value = { type: classifyAxiosError(e), raw: e } throw e } finally { loading.value = false } } if (immediate) run() return { data, loading, error, run } }

data用shallowRef而不是ref：接口返回的通常是列表或对象，深层响应式代理在几千条数据时开销可观，而业务里一般整体替换、不做深修改。run用try/finally保证无论成功失败loading都会归位。error里既放分类结果又放原始错误，页面可以按error.type === 'timeout'显示"重试"按钮，也可以把raw上报给监控。模板里就是const { data, loading, error, run } = useRequest(fetchList, { immediate: true })，业务侧不再出现任何catch分支。

5.2 三个动作验证超时链路是否真的接通

写完不等于生效。我一般按这三步走一遍：

第一步，用浏览器 DevTools 的 Network 面板把请求改成Slow 3G，同时把接口的 timeout 临时改成 800ms。观察是否弹出warning提示、是不是只弹了一次、点击重试按钮能不能重新发出请求。

第二步，用 Node 起一个故意不返回的服务，验证数以秒计的慢响应。

# 起一个 30 秒才响应的接口，用于本地验证 node -e " require('http').createServer((req, res) => { setTimeout(() => { res.writeHead(200); res.end('{\"code\":0}') }, 30000) }).listen(3000, () => console.log('slow api on :3000')) "

把请求指向http://localhost:3000，如果 10 秒时如期抛出ECONNABORTED并走到timeout分支，说明拦截器和分类函数都正常。第三步，切路由离开当前页面，看 Network 面板里在途请求状态是否变成canceled，同时确认没有控制台警告——如果出现 "Cannot read properties of null"，多半是某个组件没走useAbortable，还在往已卸载的实例上写数据。

第三步最容易漏，也最值得做成 CI 检查项：把ERR_CANCELED静默处理、组件卸载时 abortAll、多请求 loading 计数归零这三件事写成几条断言，比事后翻用户录屏省事得多。

本文还有配套的精品资源，点击获取