企业官网建设流程全解析

做前端这些年，跟Axios打交道的时间比跟部分同事还熟。跨域这个问题，几乎每个前端都遇到过——控制台一片红色，Network里清清楚楚显示请求发出去了，但response就是拿不回来。很多人第一反应是“Axios是不是出问题了”，实际上Axios只是背锅侠，真正拦路的是浏览器同源策略。

这篇文章我把这几年折腾Axios跨域的所有经验整理成10招，从本地开发的代理配置到生产环境的Nginx反代，从服务端CORS设置到JSONP保底，还会聊一些比较冷门但实战中真的会踩的坑，比如multipart上传时的Content-Type、升级Axios版本后请求发不出去、谷歌浏览器升级导致的跨域请求失败等等。无论你是刚接触前端的小白，还是被项目里奇怪的跨域报错折磨了半个月的老手，都能从这里找到对应的解法。

1. 先弄清楚Axios跨域报错的源头

1.1 同源策略与Origin到底怎么理解

跨域这个词听着玄乎，拆开就一句话：浏览器只允许页面去请求“同源”的资源。所谓同源，是协议、域名、端口三个都得一样。比如你的前端页面跑在http://localhost:5173，后端接口是http://localhost:8080/api/user，端口都不一样，这就跨域了。

热词里有句话问得特别好：“origin是源头的意思，那为什么cross-origin就翻译为跨域呢？”这个问题其实把概念搞懂了一半。Origin在浏览器里指的是“请求的来源”，由协议+域名+端口组成，比如http://localhost:5173。当浏览器发请求时，会自动带上一个Origin头，后端拿到这个头就知道请求来自哪里。如果这个Origin和当前页面的地址对不上，或者和接口地址不在同一个源，就叫cross-origin，翻译成跨域是顺理成章的事。

同源策略限制的不是“服务器能不能收到请求”，而是“浏览器能不能接收服务器的响应”。这个区别非常关键。请求其实发出去了，服务器也正常返回了，但浏览器拿到响应后一检查，发现Origin不匹配，直接抛出一个CORS错误，把响应丢进垃圾桶。所以你在Network里能看到请求状态可能是200，但代码里catch到的却是ERR_NETWORK或者一串CORS报错，就是这个原因。

1.2 请求到底发出去没有：跨域报错的三种形态

我刚转前端那会儿，经常被跨域报错搞懵，后来总结出三种典型形态，遇到问题先对号入座，能省很多排查时间：

第一种是简单请求的CORS报错。GET、POST且Content-Type是text/plain、application/x-www-form-urlencoded、multipart/form-data之一，这种请求不会触发预检，浏览器直接拦截响应，控制台报Access to XMLHttpRequest at 'xxx' from origin 'yyy' has been blocked by CORS policy。解决方法就是让服务端把Access-Control-Allow-Origin响应头加正确。

第二种是预检请求失败。当请求带自定义Header、Content-Type是application/json、或者用了PUT、DELETE等方法时，浏览器会先发一个OPTIONS请求去试探，如果服务端没正确处理这个预检请求，真实请求根本不会发出。后面我会专门讲预检请求这条，这是后端同事最爱忽略的部分。

第三种是请求压根没走对。比如本地开发时baseURL写成了http://localhost:8080而没走代理，接口路径又没拼对，看起来像是跨域问题，其实是路径404。这种最容易迷惑人，排查的时候先看Network里的请求URL是不是对的，再看响应状态码，别一上来就怀疑是CORS。

1.3 一张表看清10招的适用场景

跨域解法这么多，难点不在“怎么配”，而在“什么时候该用哪种”。下面这张表是我平时给团队做技术方案时用的，直接照着选就行。

2. 面向开发环境的招数

2.1 第1招：vite/webpack开发代理一把梭

本地开发是跨域问题的高发区，因为前端起在5173端口，后端接口可能在8080、9090甚至完全另一台服务器上。最简单的解法就是让开发服务器当中间人：前端所有请求都发给本地开发服务器，由它转发给真实后端。因为服务器之间的请求不受浏览器同源策略约束，跨域问题直接消失。

Vite项目在vite.config.js里配：

export default defineConfig({ server: { proxy: { '/api': { target: 'http://192.168.1.100:8080', changeOrigin: true, rewrite: path => path.replace(/^\/api/, '') } } } })

Webpack项目则在vue.config.js或webpack.config.js里配：

devServer: { proxy: { '/api': { target: 'http://192.168.1.100:8080', changeOrigin: true, pathRewrite: { '^/api': '' } } } }

这里有几个容易被忽略的点。第一是changeOrigin必须设成true，它会把请求头的Host改成目标地址，否则后端做域名校验时会拒绝请求。第二是rewrite或pathRewrite，因为后端接口路径一般不带/api前缀，前端统一拼上/api后，代理转发时要正确剥掉这层前缀。第三是代理只对开发环境生效，打包之后这些配置就没了，别指望它能帮你解决生产环境的问题。

2.2 第2招：Axios二次封装统一baseURL和跨域错误提示

跨域报错最大的问题不是报错本身，而是报错信息太散。简单请求被CORS拦截、预检失败、网络中断、超时，这些在Axios里最终表现都是错误，但错误码和提示语各不相同。我强烈建议每个项目都做一层Axios二次封装，把跨域相关的错误统一收敛。

我的封装思路是：只导出封装后的实例，所有业务模块都从request.js里引，不直接裸用Axios。baseURL统一从环境变量读，比如import.meta.env.VITE_API_BASE，没有就默认/api。这样换环境时只需要改环境变量，不用全局搜索替换路径。

import axios from 'axios' const service = axios.create({ baseURL: import.meta.env.VITE_API_BASE || '/api', timeout: 10000 }) service.interceptors.request.use(config => { const token = localStorage.getItem('token') if (token) { config.headers.Authorization = `Bearer ${token}` } return config }) service.interceptors.response.use( response => response.data, error => { if (error.code === 'ERR_NETWORK') { console.error('网络异常或跨域请求被拦截，请检查代理配置或服务端CORS设置') } else if (error.response?.status === 401) { // 跳登录逻辑 } return Promise.reject(error) } ) export default service

拦截器里最大的价值在于：把“跨域问题”和“网络问题”“后端错误”区分开，避免所有问题都堆在业务代码里处理。实际项目中我见过太多人每个页面都写一遍catch，还都只弹个“接口异常”，最后出了问题根本没法定位。

2.3 第3招：接口路径前缀设计

这一招看着不起眼，但它决定了前两招能不能顺利落地。很多项目接口路径乱，/login、/user/list、/order/detail全裸奔，没有统一前缀。这种项目配代理的时候就会很痛苦——你到底代理哪条路径？代理全部吧，静态资源也被转发了；代理单条吧，规则多得要命。

最好的实践是要求后端所有接口统一挂在/api前缀下面，比如/api/user/list、/api/order/detail。前端Axios的baseURL直接设成/api，代理规则只要写/api一条就能覆盖全部请求。如果后端实在不肯改，前端也可以在baseURL里拼，但后续维护体验会差很多。

做这个设计的时候有个小技巧：代理转发到后端时把/api剥掉，这样后端接口路径保持原样，不用动一行代码。以后就算把代理换成Nginx，规则也是延续同一套思路，前端的baseURL完全不用改。

2.4 第4招：uniapp等跨端项目的代理配置

热词里有人问uniapp怎么配置跨域，这个场景比较特殊。uniapp打包成小程序或App时，运行的宿主环境不是浏览器，根本没有同源策略，所以不存在跨域问题。但如果编译成H5在浏览器里跑，就绕不开浏览器同源策略。

处理方式分两步。第一步，在manifest.json的h5配置里找到devServer相关配置，如果是老版本用vue.config.js的devServer，新版用Vite的server.proxy，配置方式和上面讲的基本一样。第二步，注意uni.request和Axios在H5模式下走的是XMLHttpRequest，在小程序里走的是自己封装的请求对象，所以跨域处理只影响H5端。

我实际项目里的做法是：接口请求统一走封装后的Axios，baseURL在H5端设成/api靠代理转发，在小程序端设成完整域名。判断环境用import.meta.env.VITE_PLATFORM或者uniapp内置的条件编译方式，一套代码两端跑，跨域问题只在H5调试时出现，小程序和App完全不受影响。

3. 面向生产环境的招数

3.1 第5招：Nginx反向代理实战

开发环境的代理只是临时方案，到了生产环境，前后端一分离，跨域问题还会冒出来。最成熟的生产方案是Nginx反向代理，让Nginx同时监听前端域名，把/api开头的请求转发到后端服务。

一份我实测过很多次的Nginx配置长这样：

server { listen 80; server_name www.example.com; # 前端静态资源 location / { root /var/www/dist; index index.html; try_files $uri $uri/ /index.html; } # 接口反向代理 location /api/ { proxy_pass http://backend-server:8080/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } }

注意proxy_pass那行结尾的斜杠，这是个经典大坑。http://backend-server:8080/末尾带斜杠，转发时会把/api前缀去掉，也就是/api/user/list会被转发成/user/list。如果想去掉/api，就写带斜杠；如果想保留，就写http://backend-server:8080不带斜杠。这个细节我至少看到三个同事栽过，前端请求一路200，但返回的数据永远是404页面。

3.2 第6招：同源部署一劳永逸

如果项目是内部系统，或者你有能力决定部署架构，强烈建议用同源部署。什么意思呢？把前端打包后的静态文件，直接放在后端服务能访问的地方，或者让后端把前端dist目录当成静态资源目录。这样前端页面和后端接口跑在同一个域名和端口下，同源策略天然不触发，连CORS配置都省了。

Spring Boot项目里可以把dist目录放到src/main/resources/static下，或者单独配置一个静态资源映射。Node后端更简单，用express.static指一下目录就行。同源部署不是偷懒，它是最稳的方案——你不在浏览器层面解决跨域，而是压根不让跨域发生。唯一要注意的是，前端路由如果是history模式，需要后端把不存在的路径都返回index.html，否则刷新页面会404。

4. 服务端配合的招数

4.1 第7招：CORS响应头全面配置

跨域问题光有前端折腾没用，真正彻底的解法在后端。CORS的全称是Cross-Origin Resource Sharing，浏览器提供的一套机制：只要服务端在响应头里明确告诉浏览器“这个来源的请求我允许”，浏览器就会放行。

后端需要设置的响应头有这几个，我列个对照表方便你直接拿去跟后端对：

有个细节值得强调：Access-Control-Allow-Origin返回*虽然方便，但只要前端请求带了Cookie，浏览器就会拒绝。所以凡是涉及登录态的接口，服务端必须动态返回请求的Origin，而不是写死*。

4.2 第8招：预检请求OPTIONS处理

后端同事最常问的问题就是：为什么我接口调得好好的，控制台里突然多了一个OPTIONS请求？这个OPTIONS就是预检请求。刚才讲过，当你的Axios请求用了application/json、自定义Header、或者PUT、DELETE等方法时，浏览器会先问服务端：我能不能发这个请求？服务端回答说可以，浏览器才发真正的请求。

后端处理预检的思路很简单：对OPTIONS请求直接返回200，不要走业务逻辑，同时把上面CORS的响应头都带上。如果后端没处理OPTIONS，最常见的结果就是真实请求压根没发出去，前端只看到一个NetWork error。这个问题的排查特征是：Network里只有OPTIONS请求，永远等不到后面的GET或POST。

我遇到过很多次，后端框架已经自动处理了CORS，但自定义拦截器在OPTIONS请求上直接返回了401，导致预检失败。所以做后端接口时，所有拦截器都要放行OPTIONS请求，这是最容易踩坑的地方。

4.3 第9招：withCredentials携带Cookie

跨域请求默认不带Cookie，这是浏览器安全策略的一部分。你的请求如果依赖Session或登录态Cookie，就算CORS配置好了，后端还是拿不到登录凭证，接口报401或者未登录。

前端解法是在Axios请求里把withCredentials设为true：

axios.defaults.withCredentials = true

如果是二次封装的实例，就在创建时指定：

const service = axios.create({ baseURL: '/api', timeout: 10000, withCredentials: true })

但这只是前半步。后端在响应Access-Control-Allow-Origin头时不能返回*，必须返回具体的前端Origin，同时加上Access-Control-Allow-Credentials: true。两个条件缺一不可，少一个浏览器都会把响应拦下来。

5. 特殊场景的招数

5.1 第10招：JSONP兜底方案

JSONP是个老掉牙但依然有用的方案。它的核心思路是：script标签加载资源不受同源策略限制。既然XHR被浏览器拦截，那就用动态创建script标签的方式加载接口，接口返回的是一段JS代码，里面调用你定义好的回调函数，把数据当成参数传进来。

Axios本身没有原生JSONP支持，需要自己封装一个简单实现：

export function jsonp(url, params = {}, callback = 'callback') { return new Promise((resolve, reject) => { const script = document.createElement('script') const callbackName = `jsonp_${Date.now()}_${Math.random().toString(16).slice(2)}` const query = new URLSearchParams({ ...params, [callback]: callbackName }).toString() window[callbackName] = data => { delete window[callbackName] document.body.removeChild(script) resolve(data) } script.src = `${url}?${query}` script.onerror = () => { delete window[callbackName] document.body.removeChild(script) reject(new Error('JSONP加载失败')) } document.body.appendChild(script) }) }

JSONP的局限性很明显：只能发GET请求，无法POST大表单，没法上传文件，也没有统一的错误码机制。它是老接口时代的产物，现在新项目基本用不到，但万一你接的第三方老系统只支持JSONP，这一招能救命。

5.2 彩蛋一：multipart/form-data上传时的Content-Type坑

热词里提到“axios multipart”和“content-type使用表单模式”，这俩放到一起说，因为它们是同一个坑的两面。

用Axios上传文件，正确姿势是构造FormData对象，让Axios自动设置Content-Type，千万别手动指定application/json：

const formData = new FormData() formData.append('file', file) formData.append('name', '张三') axios.post('/api/upload', formData)

如果你不手动设置Content-Type，Axios会检测到数据是FormData类型，自动帮你带上multipart/form-data; boundary=xxx。这个boundary是分界线，后端要靠它解析各个字段。一旦你手动写了application/json，boundary丢失，后端解析不出文件内容，直接报“缺少文件参数”或返回400。

另一个常见的坑是升级Axios版本后，如果拦截器里手动处理了headers，可能会把Content-Type覆盖掉，导致同样的代码从能用变成不能用。遇到上传接口突然挂了，优先检查Content-Type有没有被拦截器改掉。

5.3 彩蛋二：WebSocket/Socket.io到底有没有跨域

热词里有人问“socket有跨域吗”，答案是：WebSocket不受同源策略约束，但服务器会在握手阶段检查Origin头。

简单解释一下原理。WebSocket是浏览器通过HTTP升级协议建立的TCP长连接，它不走XMLHttpRequest那套流程，所以浏览器不会在响应阶段做CORS拦截。但这不代表服务器可以完全不管，因为任何人都可以从任意页面发起WebSocket连接，服务器端必须校验握手请求里的Origin头是不是自己信任的来源，否则容易被恶意站点利用，搞出连接劫持或数据窃取。

所以你的Axios管不到WebSocket，跨域问题要从后端Socket服务入手，让服务端在onConnection或握手中间件里做Origin白名单校验。

6. 跨域问题排查与避坑手册

6.1 谷歌浏览器导致的跨域问题怎么解决

热词里有个很扎心的问题：“谷歌浏览器导致的跨域问题怎么解决”。这个问题我研究过，浏览器本身不制造跨域问题，它只是严格执行同源策略，但很多情况下确实是浏览器更新后行为变化，让原本能跑的代码突然跑不动了。

最常见的是Chrome对第三方Cookie的逐步限制。以前老版本浏览器在跨域请求中默认带Cookie，现在逐步改成需要显式声明SameSite和Secure属性，导致跨域请求的Cookie丢失，接口返回401。排查方法：打开Network，看请求里有没有Cookie头；没有的话，检查接口的Set-Cookie响应头里SameSite属性是什么，必要时改成SameSite=None; Secure，并确保前端withCredentials开启。

另一种是浏览器插件干扰。某些广告拦截插件、翻译插件会注入或修改请求头，把Origin改成chrome-extension://xxx，服务端一看Origin不认识，CORS自然就挂了。我在本地调试时遇到过几次，现象是别人电脑上没问题，到我电脑上所有跨域请求都报错。排查方法：隐身模式启动浏览器，禁用所有插件再试一次，马上就能定位。

6.2 升级Axios版本后请求发不出去的案例

热词里有一条说得很具体：“升级前浏览器发送的报文是json，升完级axios后，发送”。这种问题我遇到过，axios从0.x升级到1.x，默认行为有几个变化容易踩坑。

0.x版本里，如果data传的是对象，Axios会根据Content-Type帮你序列化；1.x版本对transformRequest的要求更严格，如果拦截器里覆盖了transformRequest，可能导致Content-Type没有被正确设置，最终发给后端的报文格式跟后端预期对不上。

真实案例是这样：老项目用axios 0.21，拦截器里对请求data做了一层格式化，接口一直正常。升级到1.6后，所有POST接口突然报错，后端说收到的报文不是JSON。排查下来发现，拦截器里的transformRequest把JSON.stringify的逻辑覆盖了，但没保留默认的Content-Type设置。解决办法是重写拦截器逻辑，要么删掉自定义transformRequest，要么在transformRequest里显式加上Content-Type: application/json。这个坑很隐蔽，因为报错不在浏览器控制台，而是后端的解析错误，没有日志对照根本发现不了。

6.3 一份常用跨域排查清单

被跨域折磨到崩溃的时候，按这个顺序检查，半小时内基本能定位问题：

1. 打开浏览器Network，确认请求真的发送了，看请求URL和预期是否一致。
2. 如果请求状态是CORS error，选中请求看响应头里有没有Access-Control-Allow-Origin。
3. 如果有OPTIONS预检请求，查看预检的响应状态码和CORS相关响应头，重点看Access-Control-Allow-Methods和Access-Control-Allow-Headers是否覆盖了实际请求的方法和头。
4. 请求带了Cookie吗？如果带了，检查Access-Control-Allow-Origin是不是具体的源而不是*，再确认Access-Control-Allow-Credentials有没有设为true。
5. 本地开发确认代理只作用于开发服务器，生产环境确认请求打在了Nginx或其他网关上。
6. 检查环境变量，baseURL在不同环境下的值是否正确，不要出现生产环境还在请求localhost或/api没有对应代理的情况。
7. 最后排查是不是浏览器插件或浏览器版本策略变动的锅，用隐身模式复现一次。

我个人在实际项目里的体会是，跨域问题80%都是配置问题，而不是代码问题。只要把开发代理、生产反代、CORS响应头这三环搞清楚，绝大多数项目都能跑得通。真正让人崩溃的是那些隐藏条件，比如withCredentials和Allow-Origin的联动、OPTIONS预检被拦截器拦掉、上传文件时Content-Type被覆盖，这些东西不遇到一次，光看文档永远记不住。希望这10招加2个彩蛋能帮你少走点弯路。