在React开发里代理配置大概是每个前后端联调的人都绕不开的一个坎。不管是用了Create React App这种脚手架还是自己手搓Webpack配置跨域问题就像一只拦路虎卡在你和接口数据之间。我记得刚转前端那会儿为了调通一个登录接口愣是折腾了一个下午后来才发现不过是代理没配好而已。今天就把这块彻底讲清楚从为什么需要代理讲到实际怎么配再到那些没人明说的坑一次性看完你就能自己动手了。这篇内容主要适合正在做React开发、遇到了跨域报错或者想搞清楚proxy到底在开发环境里起了什么作用的同学。即使你用的是Vite或者其他框架核心思路也是相通的换个配置入口就行。我先说说为什么开发时需要代理然后给你完整的配置方案和调试技巧。1. 为什么React开发离不开代理配置1.1 浏览器跨域机制是根本原因很多人一开始不理解明明接口地址和组织架构都是对的为什么浏览器就是不让请求通过这一切都源于浏览器的同源策略。简单说浏览器规定当前页面所在的协议、域名、端口和发请求的目标地址完全一致才叫同源否则就是跨域。React开发环境下前端通常跑在http://localhost:3000而后端接口往往在http://localhost:8080或者某个测试服务器上端口不同甚至域名不同浏览器就会拦截响应。这种拦截很微妙你打开开发者工具会发现请求实际上发出了后端也处理了并返回了数据但浏览器在拿到响应时发现跨域就直接把这个响应丢掉了前端代码根本读不到数据。这是“代理”之所以存在的根本原因——我们需要一个中间人让请求看起来就像是从前端自己的服务器发出去的绕开浏览器同源策略的限制。1.2 开发环境与生产环境的本质差异生产环境里前端打包后通常部署在静态服务器上同域名下通过Nginx这类服务把/api开头的请求反向代理给后端所以线上没有跨域问题。但本地开发时你不可能也搭一套Nginx这时候就需要前端开发服务器也就是Webpack Dev Server自己充当那个代理角色。这里有个关键点开发服务器是从Node.js层面派发请求的Node.js本身没有同源策略约束所以它去请求后端接口是完全畅通的。浏览器只看到前端服务器返回的结果而前端服务器会帮你把请求转发给真正的接口服务器再拿到结果回来给浏览器。整个过程就是一次“代理转发”浏览器全程感知不到跨域的存在。1.3 代理配置的本质和好处代理配置本质上就是告诉开发服务器当你看到某些特定路径的请求时不要试图去本地找文件而是转发到配置好的目标地址去。这样你不仅解决了跨域还能在本地代码里继续使用简洁的接口路径。比如你请求/api/login代理会自动转发到http://localhost:8080/login后端的路径甚至不需要改。配置代理还有个意外的好处它可以帮你绕过开发环境里那些不规范的接口设计问题。比如后端接口没有统一加/api前缀你就可以在代理里做路径重写。这种灵活性在真实的项目里会帮你省下大量联调时间。2. 代理配置的几种主流方案2.1 Create React App的极简代理方案如果你用的是Create React App创建的项目最简单的方式就是在package.json里加一个字段proxy: http://localhost:8080然后在代码里直接请求相对路径就行fetch(/api/user)开发服务器会自动把这个请求转发到http://localhost:8080/api/user。这里的/api可以任意写只要后端接口确实有这个路径就行。这种方式的优点是零配置适合只有一个后端服务、接口路径基本一致的小项目。但用这个方案有很明显局限它只能配置一个目标地址如果你同时需要联调多个后端服务或者某个接口要走不同服务器它就不够用了。另外Create React App官方也提醒过这个proxy字段仅支持HTTP和HTTPS协议如果你需要WebSocket代理就得换下面的方法。2.2 基于http-proxy-middleware的灵活配置Create React App提供了自定义代理的入口在src目录下新建setupProxy.js文件配合http-proxy-middleware这个库来做。这是目前最主流也是最推荐的方式因为它的控制粒度非常细。你不仅可以指定不同的路径走不同的目标服务器还可以设置路径重写、WebSocket支持、安全证书校验等选项。先安装依赖npm install http-proxy-middleware --save然后在setupProxy.js里写const { createProxyMiddleware } require(http-proxy-middleware); module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true }) ); };这段代码的意思是当你请求/api开头的路径时开发服务器会把请求转发到http://localhost:8080并保留原来的路径。比如请求/api/user最终转发给后端的就是http://localhost:8080/api/user。这里的createProxyMiddleware就是核心它支持非常多的配置项后面我会逐个拆解参数含义。相比package.json里的proxy这种方式可以配置多个代理规则例如module.exports function(app) { app.use(/api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true })); app.use(/auth, createProxyMiddleware({ target: http://localhost:9090, changeOrigin: true })); };这样/auth开头的请求就会走到9090端口去灵活多了。2.3 自定义Webpack配置方案如果你的项目没有使用Create React App而是自己搭建的Webpack环境那就在webpack.config.js里的devServer字段里配置。本质上和setupProxy.js是一样的因为Create React App内部也是把setupProxy.js转成devServer.proxy配置。区别只在于形式。module.exports { // ... devServer: { proxy: [ { context: [/api, /auth], target: http://localhost:8080, changeOrigin: true } ] } };也可以用对象形式配置带路径的devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }其实开发服务器底层用的还是http-proxy-middleware所以配置项是完全通用的。实践中最常见的问题反而是大家不知道setupProxy.js和devServer.proxy是同一个东西的不同写法导致配置错地方找不到问题。3. 实操手把手配置一个完整的React代理3.1 先识别你的接口请求特征动手配置前先想清楚你的请求到底长什么样。比如后端接口地址是http://192.168.1.100:8080/api/user/list而你前端代码里打算只写/api/user/list那代理规则就很简单直接匹配/api前缀即可。但如果后端接口路径乱七八糟比如有/api/user/list、/v2/order/detail你就需要决定到底是用统一的/api前缀匹配还是用多个规则。我的建议是所有需要代理的请求统一带一个/api前缀这样后端可以做路径区分前端代理也只用写一条规则。如果后端非要不同前缀那就老老实实写多个规则。3.2 根据项目类型选择配置入口我再帮你做一个快速判断如果你用的是Create React App直接建setupProxy.js最好。如果你用的是Vite配置在vite.config.js里通过server.proxy字段。如果你是自己搭建的Webpack环境那就去devServer.proxy里写。这三种入口的配置思路一模一样只是写法略有差异。下面我以Create React App的setupProxy.js为例完整演示一遍。3.3 完整代码示例与参数解读假设项目结构是这样的前端开发地址http://localhost:3000后端接口地址http://192.168.1.100:8080接口路径前缀/api后端实际不需要/api前缀即请求/api/user要转发成/user此时配置如下const { createProxyMiddleware } require(http-proxy-middleware); module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://192.168.1.100:8080, changeOrigin: true, pathRewrite: { ^/api: } }) ); };这里pathRewrite的作用就是路径重写。正则^/api的意思是把路径开头匹配到的/api替换成空字符串。所以/api/user会被重写成/user再拼接到target地址后面最终请求变成http://192.168.1.100:8080/user。这就是“前后端路径不一致”场景下最关键的配置项。changeOrigin: true这个配置很多人忽略但它极其重要。它的作用是修改代理请求头里的Host字段。如果不设置成true后端服务器收到的请求头Host还是localhost:3000有些后端框架在验证域名时会直接返回403或者校验不通过。设置为true后Host会变成target指定的地址后端就认你是合法的同源请求了。除了这两个配置还有几个常用参数secure: false如果后端的接口是HTTPS协议但是自签名证书或者测试环境证书不受信任就需要设置这个为false让代理跳过证书校验。不然请求会直接被Node.js层的证书错误卡死。ws: true如果你想代理WebSocket请求在配置里带上这个就行。比如做实时通知时前端用Socket.io连接/socket就需要打开WebSocket代理支持。logLevel: debug调试代理问题的时候这个选项会输出详细的日志能帮你看到实际转发的目标地址。3.4 多目标环境的代理配置实战真实的开发场景里你经常会遇到“一套前端、多个后端”的情况。比如用户相关接口走A服务订单相关接口走B服务。这时候推荐用对象形式配置module.exports function(app) { app.use(createProxyMiddleware(/user, { target: http://user-service:8080, changeOrigin: true })); app.use(createProxyMiddleware(/order, { target: http://order-service:9090, changeOrigin: true })); };这里注意createProxyMiddleware第一个参数可以传路径字符串也可以传路径数组还可以直接不传然后在配置里通过context字段指定。我更推荐传路径的方式因为代码可读性强。还有一个细节匹配规则是按先后顺序执行的。你把哪个规则写在前面它就优先生效。因此像/api/user这种具体路径的规则要写在/api这种通用规则之前不然永远匹配不到具体的规则。我见过一个朋友把精确规则放在后面结果请求一直被通用规则截胡代理结果怎么都不对。3.5 配置完成后如何验证效果配置写好之后并不是马上就能生效的。如果你用的是setupProxy.js方式它会在开发服务器启动时加载所以每次修改这个文件都需要重启开发服务器。很多人改了之后发现没反应第一反应是代码写错了其实只是没重启。重启之后打开浏览器开发者工具的Network面板发一个请求看看结果。你会在请求列表里看到发送的地址是http://localhost:3000/api/user但响应的数据来自后端。如果你在Network里看到请求状态是200且返回了数据说明代理正常工作。如果看到304或者跨域拦截报错那就说明代理没配上继续检查配置入口。还有一个验证技巧在setupProxy.js里加一行console.log(proxy loaded)启动时如果控制台打印了这行日志说明文件被加载了代理规则在生效。如果没打印就得检查文件放的位置对不对。4. 常见问题与排查技巧实录4.1 代理不生效请求直接打到本地这是最常见的问题。表现是请求一直失败或者返回的是前端编译后的HTML而不是后端的数据。排查思路其实很简单四处排查缺一不可确认文件是否真的在src目录下。Create React App只会加载src/setupProxy.js放错了位置并不会报错但也不会生效。确认代码里是否真的使用相对路径请求。如果你在代码里写了完整的http://192.168.1.100:8080/api/user那代理根本不会管你因为浏览器直接发跨域请求了。代理只拦截相对路径请求比如/api/user。确认是否重启。改完配置必须重启开发服务器热更新不会加载新代理规则。确认后端地址可访问。先用浏览器或者Postman直接请求target地址看看接口本身是否正常。我会把这个问题做成一个速查表方便你以后遇到直接对号入座现象可能原因处理方式请求返回HTML内容代理规则没生效请求落到了开发服务器上检查setupProxy.js路径、是否重启请求返回403后端Host校验失败设置changeOrigin: true请求返回证书错误后端是HTTPS但证书不受信任设置secure: false接口数据时好时坏后端并发处理慢检查代理多实例配置或调整后端超时WebSocket连接失败未开启WebSocket代理添加ws: true参数4.2 路径重写规则总是写不对很多人在pathRewrite里犯晕其实只要记住一个原则重写是针对“代理匹配到的路径”做的替换。如果你的代理匹配的是/api那么重写^/api: 就是去掉路径开头的/api。如果你的代理匹配的是/api/user那应该重写成^/api/user: 这样请求/api/user/login就会变成/login。正则里的^是“开始匹配”的意思不加的话可能会误重写到路径中间的相同字段。另外重写可以连续替换多次用对象形式一次性写多个规则pathRewrite: { ^/api: /, ^/old: /new }配置顺序是从上往下依次执行的注意别让前面的规则把后面的规则需要匹配的字符替换掉了。我建议多用几个不同的路径请求做测试确认重写结果符不符合预期。如果拿不准可以用console.log在代理中间件里打印重写后的URLhttp-proxy-middleware的源码支持这样的调试。4.3 代理配置与环境变量组合使用另一个实际项目里经常出现的需求是不同环境代理到不同地址。开发环境可能代理到本地后端测试环境代理到测试服务器。这时候建议在代码里读取环境变量动态生成代理配置。const { createProxyMiddleware } require(http-proxy-middleware); const API_TARGET process.env.REACT_APP_API_HOST || http://localhost:8080; module.exports function(app) { app.use( /api, createProxyMiddleware({ target: API_TARGET, changeOrigin: true, pathRewrite: { ^/api: } }) ); };这样你只需要在启动命令里设置环境变量REACT_APP_API_HOSThttp://157.245.3.15:8080 npm start就可以在不改动代码的情况下切到目标环境。很多人误以为环境变量只能在浏览器代码里用其实在setupProxy.js这个Node.js环境里也是能读到的因为它是开发服务器端运行的。4.4 代理带来的缓存与路径问题代理配置好之后还有个容易踩的坑是缓存。有时候你改了后端代码但前端的请求一直返回旧数据很可能不是代理问题而是浏览器HTTP缓存。这时候在Network里可以看到304 Not Modified或者200 (from disk cache)。处理方法是在请求头里加Cache-Control: no-cache或者在接口地址后加个时间戳。另外如果你的开发服务器启用了historyApiFallback或者React Router使用了BrowserRouter那么刷新某个子路由页面时会出现404。原因是开发服务器不知道代理规则之外的路径应该返回index.html还是交给后端。这种情况需要额外配置historyApiFallback选项把未知路径都重定向到index.html同时确保代理规则优先匹配接口请求。Create React App默认处理好了这层逻辑但如果是自定义Webpack就要自己设置。5. 高级用法代理场景下的认证与Cookie处理很多项目在联调时会碰到登录状态失效的问题表现是请求都能通但后端一直说没有登录凭证。这多半是因为你在代理请求时没有处理好Cookie和认证头。http-proxy-middleware里有一个onProxyReq事件你可以在请求转发前检查并修改请求头。比如你需要把浏览器的Cookie透传给后端或者是从本地存储里读取一个token加到请求头上module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, onProxyReq(proxyReq, req, res) { if (req.headers[cookie]) { proxyReq.setHeader(cookie, req.headers[cookie]); } } }) ); };默认情况下http-proxy-middleware已经帮你透传了大部分请求头但如果你遇到Cookie丢失或者自定义请求头丢失的情况就需要用onProxyReq来手动补齐。同样用onProxyRes可以在接收后端响应后修改响应头比如处理跨域需要的Access-Control-Allow-Origin这类字段不过因为有代理这种情况很少见了。这里还要注意一个小细节如果你是在setupProxy.js里读取环境变量或本地文件比如process.env.LOCAL_TOKEN记得不要把它打包进生产代码因为setupProxy.js只存在于开发环境生产构建时会自动忽略它。你要是把敏感信息放在这个文件里不用担心安全性。6. 调试代理配置的独家技巧说实话我在调试代理问题时遇到过不少奇怪的现象。很多文档从来没提过但它们真的很能救人一命。第一个技巧是用http-proxy-middleware的logLevel选项。配置logLevel: debug之后在终端里你能看到完整的转发链路比如“请求/api/user被转发到http://192.168.1.100:8080/user”。这个信息能直接验证你对pathRewrite的理解有没有问题。第二个技巧是写一个临时的测试接口。我经常在开发服务器里给根路径写一个简单的/ping接口然后用浏览器直接访问http://localhost:3000/ping来验证服务器本身是否正常。如果/ping都打不开说明开发服务器自己挂了跟代理没关系。反过来如果/ping正常但带/api的请求异常问题就锁定在代理规则上。第三个技巧是善用浏览器的curl命令。在终端里用以下命令直接测试目标地址curl http://localhost:8080/api/user -H Origin: http://localhost:3000看返回的响应头里有没有允许跨域的字段。如果响应头缺失那就说明后端可能需要额外配置跨域策略光靠代理其实已经能通了。这类问题经常让我误以为代理没生效其实是后端自己也在做跨域限制。6.1 一个典型的调试实录我记忆里有次帮朋友排查代理问题现象很奇怪手机访问开发服务器能正常拿到数据但电脑浏览器却一直报跨域错误。两边访问的是同一个地址同一个网络为什么结果不一样后来发现电脑浏览器缓存了旧的Service Worker导致请求走了缓存一直没发到代理规则里。清除站点数据后马上恢复。这件事提醒我遇到代理问题时先想到“清理缓存”这个经典操作。类似的还有浏览器插件干扰。某些安全插件会拦截常见接口地址导致请求看起来是代理转发出去的但实际上被插件拦了。这种情况在Chrome的隐身模式里往往就消失了。所以代理配置调试一旦陷入困局先用隐身模式测试往往能排除一大批环境干扰因素。6.2 代理配置的最佳实践清单经过这么多年项目磨炼我总结了一套适合所有React项目的代理配置最佳实践。无论你是新项目还是老项目照着这套来基本上不会掉坑。我把这些实践分成三个层面配置层面优先使用setupProxy.js而不是package.json的proxy字段扩展性更好所有代理请求统一加/api前缀路径重写时保持一致性changeOrigin永远设置为true涉及HTTPS目标时设置secure: false并加注释说明原因工程层面用环境变量管理不同环境的代理目标地址代理配置里不要写死IP用相对路径并从环境变量读取定期用logLevel: debug验证代理目标是否符合预期运维层面修改代理配置后必须刷新浏览器缓存再测试在团队文档里写清楚每个代理规则对应哪个后端服务免得后人看不懂这个清单看着简单但真的执行到位能帮你省掉一大堆不必要的联调时间。我见过太多同事被代理问题折磨到怀疑人生最后发现只是少加了一个changeOrigin: true。自己在项目里配代理时最让我印象深刻的教训是永远不要假设配置项能一次到位。每写完一个代理规则我都会用不同路径多测几个请求确认路径重写、HTTP头、Cookie这几项都正常再继续下一个环节。有些问题光靠看配置是看不出来的必须实际请求一遍才能暴露。比如有一次我以为pathRewrite规则写对了结果请求发出的还是带着/api排查半天才发现正则里多了一个空格这种低级错误你很难在代码审查里发现真正请求时才会暴露。后来我习惯在pathRewrite里故意保留一段明文字符串做测试比如^/api: /test再通过日志打印出来的地址判断重写是否生效确认没问题再改成实际目标路径。代理这东西从原理到实践其实都不复杂复杂的是你面对的真实项目总有自己的乱七八糟的路径和多个服务互相调用。只要理解了“开发服务器替你转发请求”这个核心原理再掌握我今天说的这几个配置入口和调试手法你就已经能应对绝大多数场景了。后面遇到问题的时候记得先把请求日志打开看目标地址和实际路径基本就成功一半了。 
长河君 · 2026/10/17 15:20:32 · 阅读 1.2k React开发代理配置详解：跨域原理、主流方案与避坑指南
在React开发里代理配置大概是每个前后端联调的人都绕不开的一个坎。不管是用了Create React App这种脚手架还是自己手搓Webpack配置跨域问题就像一只拦路虎卡在你和接口数据之间。我记得刚转前端那会儿为了调通一个登录接口愣是折腾了一个下午后来才发现不过是代理没配好而已。今天就把这块彻底讲清楚从为什么需要代理讲到实际怎么配再到那些没人明说的坑一次性看完你就能自己动手了。这篇内容主要适合正在做React开发、遇到了跨域报错或者想搞清楚proxy到底在开发环境里起了什么作用的同学。即使你用的是Vite或者其他框架核心思路也是相通的换个配置入口就行。我先说说为什么开发时需要代理然后给你完整的配置方案和调试技巧。1. 为什么React开发离不开代理配置1.1 浏览器跨域机制是根本原因很多人一开始不理解明明接口地址和组织架构都是对的为什么浏览器就是不让请求通过这一切都源于浏览器的同源策略。简单说浏览器规定当前页面所在的协议、域名、端口和发请求的目标地址完全一致才叫同源否则就是跨域。React开发环境下前端通常跑在http://localhost:3000而后端接口往往在http://localhost:8080或者某个测试服务器上端口不同甚至域名不同浏览器就会拦截响应。这种拦截很微妙你打开开发者工具会发现请求实际上发出了后端也处理了并返回了数据但浏览器在拿到响应时发现跨域就直接把这个响应丢掉了前端代码根本读不到数据。这是“代理”之所以存在的根本原因——我们需要一个中间人让请求看起来就像是从前端自己的服务器发出去的绕开浏览器同源策略的限制。1.2 开发环境与生产环境的本质差异生产环境里前端打包后通常部署在静态服务器上同域名下通过Nginx这类服务把/api开头的请求反向代理给后端所以线上没有跨域问题。但本地开发时你不可能也搭一套Nginx这时候就需要前端开发服务器也就是Webpack Dev Server自己充当那个代理角色。这里有个关键点开发服务器是从Node.js层面派发请求的Node.js本身没有同源策略约束所以它去请求后端接口是完全畅通的。浏览器只看到前端服务器返回的结果而前端服务器会帮你把请求转发给真正的接口服务器再拿到结果回来给浏览器。整个过程就是一次“代理转发”浏览器全程感知不到跨域的存在。1.3 代理配置的本质和好处代理配置本质上就是告诉开发服务器当你看到某些特定路径的请求时不要试图去本地找文件而是转发到配置好的目标地址去。这样你不仅解决了跨域还能在本地代码里继续使用简洁的接口路径。比如你请求/api/login代理会自动转发到http://localhost:8080/login后端的路径甚至不需要改。配置代理还有个意外的好处它可以帮你绕过开发环境里那些不规范的接口设计问题。比如后端接口没有统一加/api前缀你就可以在代理里做路径重写。这种灵活性在真实的项目里会帮你省下大量联调时间。2. 代理配置的几种主流方案2.1 Create React App的极简代理方案如果你用的是Create React App创建的项目最简单的方式就是在package.json里加一个字段proxy: http://localhost:8080然后在代码里直接请求相对路径就行fetch(/api/user)开发服务器会自动把这个请求转发到http://localhost:8080/api/user。这里的/api可以任意写只要后端接口确实有这个路径就行。这种方式的优点是零配置适合只有一个后端服务、接口路径基本一致的小项目。但用这个方案有很明显局限它只能配置一个目标地址如果你同时需要联调多个后端服务或者某个接口要走不同服务器它就不够用了。另外Create React App官方也提醒过这个proxy字段仅支持HTTP和HTTPS协议如果你需要WebSocket代理就得换下面的方法。2.2 基于http-proxy-middleware的灵活配置Create React App提供了自定义代理的入口在src目录下新建setupProxy.js文件配合http-proxy-middleware这个库来做。这是目前最主流也是最推荐的方式因为它的控制粒度非常细。你不仅可以指定不同的路径走不同的目标服务器还可以设置路径重写、WebSocket支持、安全证书校验等选项。先安装依赖npm install http-proxy-middleware --save然后在setupProxy.js里写const { createProxyMiddleware } require(http-proxy-middleware); module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true }) ); };这段代码的意思是当你请求/api开头的路径时开发服务器会把请求转发到http://localhost:8080并保留原来的路径。比如请求/api/user最终转发给后端的就是http://localhost:8080/api/user。这里的createProxyMiddleware就是核心它支持非常多的配置项后面我会逐个拆解参数含义。相比package.json里的proxy这种方式可以配置多个代理规则例如module.exports function(app) { app.use(/api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true })); app.use(/auth, createProxyMiddleware({ target: http://localhost:9090, changeOrigin: true })); };这样/auth开头的请求就会走到9090端口去灵活多了。2.3 自定义Webpack配置方案如果你的项目没有使用Create React App而是自己搭建的Webpack环境那就在webpack.config.js里的devServer字段里配置。本质上和setupProxy.js是一样的因为Create React App内部也是把setupProxy.js转成devServer.proxy配置。区别只在于形式。module.exports { // ... devServer: { proxy: [ { context: [/api, /auth], target: http://localhost:8080, changeOrigin: true } ] } };也可以用对象形式配置带路径的devServer: { proxy: { /api: { target: http://localhost:8080, changeOrigin: true } } }其实开发服务器底层用的还是http-proxy-middleware所以配置项是完全通用的。实践中最常见的问题反而是大家不知道setupProxy.js和devServer.proxy是同一个东西的不同写法导致配置错地方找不到问题。3. 实操手把手配置一个完整的React代理3.1 先识别你的接口请求特征动手配置前先想清楚你的请求到底长什么样。比如后端接口地址是http://192.168.1.100:8080/api/user/list而你前端代码里打算只写/api/user/list那代理规则就很简单直接匹配/api前缀即可。但如果后端接口路径乱七八糟比如有/api/user/list、/v2/order/detail你就需要决定到底是用统一的/api前缀匹配还是用多个规则。我的建议是所有需要代理的请求统一带一个/api前缀这样后端可以做路径区分前端代理也只用写一条规则。如果后端非要不同前缀那就老老实实写多个规则。3.2 根据项目类型选择配置入口我再帮你做一个快速判断如果你用的是Create React App直接建setupProxy.js最好。如果你用的是Vite配置在vite.config.js里通过server.proxy字段。如果你是自己搭建的Webpack环境那就去devServer.proxy里写。这三种入口的配置思路一模一样只是写法略有差异。下面我以Create React App的setupProxy.js为例完整演示一遍。3.3 完整代码示例与参数解读假设项目结构是这样的前端开发地址http://localhost:3000后端接口地址http://192.168.1.100:8080接口路径前缀/api后端实际不需要/api前缀即请求/api/user要转发成/user此时配置如下const { createProxyMiddleware } require(http-proxy-middleware); module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://192.168.1.100:8080, changeOrigin: true, pathRewrite: { ^/api: } }) ); };这里pathRewrite的作用就是路径重写。正则^/api的意思是把路径开头匹配到的/api替换成空字符串。所以/api/user会被重写成/user再拼接到target地址后面最终请求变成http://192.168.1.100:8080/user。这就是“前后端路径不一致”场景下最关键的配置项。changeOrigin: true这个配置很多人忽略但它极其重要。它的作用是修改代理请求头里的Host字段。如果不设置成true后端服务器收到的请求头Host还是localhost:3000有些后端框架在验证域名时会直接返回403或者校验不通过。设置为true后Host会变成target指定的地址后端就认你是合法的同源请求了。除了这两个配置还有几个常用参数secure: false如果后端的接口是HTTPS协议但是自签名证书或者测试环境证书不受信任就需要设置这个为false让代理跳过证书校验。不然请求会直接被Node.js层的证书错误卡死。ws: true如果你想代理WebSocket请求在配置里带上这个就行。比如做实时通知时前端用Socket.io连接/socket就需要打开WebSocket代理支持。logLevel: debug调试代理问题的时候这个选项会输出详细的日志能帮你看到实际转发的目标地址。3.4 多目标环境的代理配置实战真实的开发场景里你经常会遇到“一套前端、多个后端”的情况。比如用户相关接口走A服务订单相关接口走B服务。这时候推荐用对象形式配置module.exports function(app) { app.use(createProxyMiddleware(/user, { target: http://user-service:8080, changeOrigin: true })); app.use(createProxyMiddleware(/order, { target: http://order-service:9090, changeOrigin: true })); };这里注意createProxyMiddleware第一个参数可以传路径字符串也可以传路径数组还可以直接不传然后在配置里通过context字段指定。我更推荐传路径的方式因为代码可读性强。还有一个细节匹配规则是按先后顺序执行的。你把哪个规则写在前面它就优先生效。因此像/api/user这种具体路径的规则要写在/api这种通用规则之前不然永远匹配不到具体的规则。我见过一个朋友把精确规则放在后面结果请求一直被通用规则截胡代理结果怎么都不对。3.5 配置完成后如何验证效果配置写好之后并不是马上就能生效的。如果你用的是setupProxy.js方式它会在开发服务器启动时加载所以每次修改这个文件都需要重启开发服务器。很多人改了之后发现没反应第一反应是代码写错了其实只是没重启。重启之后打开浏览器开发者工具的Network面板发一个请求看看结果。你会在请求列表里看到发送的地址是http://localhost:3000/api/user但响应的数据来自后端。如果你在Network里看到请求状态是200且返回了数据说明代理正常工作。如果看到304或者跨域拦截报错那就说明代理没配上继续检查配置入口。还有一个验证技巧在setupProxy.js里加一行console.log(proxy loaded)启动时如果控制台打印了这行日志说明文件被加载了代理规则在生效。如果没打印就得检查文件放的位置对不对。4. 常见问题与排查技巧实录4.1 代理不生效请求直接打到本地这是最常见的问题。表现是请求一直失败或者返回的是前端编译后的HTML而不是后端的数据。排查思路其实很简单四处排查缺一不可确认文件是否真的在src目录下。Create React App只会加载src/setupProxy.js放错了位置并不会报错但也不会生效。确认代码里是否真的使用相对路径请求。如果你在代码里写了完整的http://192.168.1.100:8080/api/user那代理根本不会管你因为浏览器直接发跨域请求了。代理只拦截相对路径请求比如/api/user。确认是否重启。改完配置必须重启开发服务器热更新不会加载新代理规则。确认后端地址可访问。先用浏览器或者Postman直接请求target地址看看接口本身是否正常。我会把这个问题做成一个速查表方便你以后遇到直接对号入座现象可能原因处理方式请求返回HTML内容代理规则没生效请求落到了开发服务器上检查setupProxy.js路径、是否重启请求返回403后端Host校验失败设置changeOrigin: true请求返回证书错误后端是HTTPS但证书不受信任设置secure: false接口数据时好时坏后端并发处理慢检查代理多实例配置或调整后端超时WebSocket连接失败未开启WebSocket代理添加ws: true参数4.2 路径重写规则总是写不对很多人在pathRewrite里犯晕其实只要记住一个原则重写是针对“代理匹配到的路径”做的替换。如果你的代理匹配的是/api那么重写^/api: 就是去掉路径开头的/api。如果你的代理匹配的是/api/user那应该重写成^/api/user: 这样请求/api/user/login就会变成/login。正则里的^是“开始匹配”的意思不加的话可能会误重写到路径中间的相同字段。另外重写可以连续替换多次用对象形式一次性写多个规则pathRewrite: { ^/api: /, ^/old: /new }配置顺序是从上往下依次执行的注意别让前面的规则把后面的规则需要匹配的字符替换掉了。我建议多用几个不同的路径请求做测试确认重写结果符不符合预期。如果拿不准可以用console.log在代理中间件里打印重写后的URLhttp-proxy-middleware的源码支持这样的调试。4.3 代理配置与环境变量组合使用另一个实际项目里经常出现的需求是不同环境代理到不同地址。开发环境可能代理到本地后端测试环境代理到测试服务器。这时候建议在代码里读取环境变量动态生成代理配置。const { createProxyMiddleware } require(http-proxy-middleware); const API_TARGET process.env.REACT_APP_API_HOST || http://localhost:8080; module.exports function(app) { app.use( /api, createProxyMiddleware({ target: API_TARGET, changeOrigin: true, pathRewrite: { ^/api: } }) ); };这样你只需要在启动命令里设置环境变量REACT_APP_API_HOSThttp://157.245.3.15:8080 npm start就可以在不改动代码的情况下切到目标环境。很多人误以为环境变量只能在浏览器代码里用其实在setupProxy.js这个Node.js环境里也是能读到的因为它是开发服务器端运行的。4.4 代理带来的缓存与路径问题代理配置好之后还有个容易踩的坑是缓存。有时候你改了后端代码但前端的请求一直返回旧数据很可能不是代理问题而是浏览器HTTP缓存。这时候在Network里可以看到304 Not Modified或者200 (from disk cache)。处理方法是在请求头里加Cache-Control: no-cache或者在接口地址后加个时间戳。另外如果你的开发服务器启用了historyApiFallback或者React Router使用了BrowserRouter那么刷新某个子路由页面时会出现404。原因是开发服务器不知道代理规则之外的路径应该返回index.html还是交给后端。这种情况需要额外配置historyApiFallback选项把未知路径都重定向到index.html同时确保代理规则优先匹配接口请求。Create React App默认处理好了这层逻辑但如果是自定义Webpack就要自己设置。5. 高级用法代理场景下的认证与Cookie处理很多项目在联调时会碰到登录状态失效的问题表现是请求都能通但后端一直说没有登录凭证。这多半是因为你在代理请求时没有处理好Cookie和认证头。http-proxy-middleware里有一个onProxyReq事件你可以在请求转发前检查并修改请求头。比如你需要把浏览器的Cookie透传给后端或者是从本地存储里读取一个token加到请求头上module.exports function(app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, onProxyReq(proxyReq, req, res) { if (req.headers[cookie]) { proxyReq.setHeader(cookie, req.headers[cookie]); } } }) ); };默认情况下http-proxy-middleware已经帮你透传了大部分请求头但如果你遇到Cookie丢失或者自定义请求头丢失的情况就需要用onProxyReq来手动补齐。同样用onProxyRes可以在接收后端响应后修改响应头比如处理跨域需要的Access-Control-Allow-Origin这类字段不过因为有代理这种情况很少见了。这里还要注意一个小细节如果你是在setupProxy.js里读取环境变量或本地文件比如process.env.LOCAL_TOKEN记得不要把它打包进生产代码因为setupProxy.js只存在于开发环境生产构建时会自动忽略它。你要是把敏感信息放在这个文件里不用担心安全性。6. 调试代理配置的独家技巧说实话我在调试代理问题时遇到过不少奇怪的现象。很多文档从来没提过但它们真的很能救人一命。第一个技巧是用http-proxy-middleware的logLevel选项。配置logLevel: debug之后在终端里你能看到完整的转发链路比如“请求/api/user被转发到http://192.168.1.100:8080/user”。这个信息能直接验证你对pathRewrite的理解有没有问题。第二个技巧是写一个临时的测试接口。我经常在开发服务器里给根路径写一个简单的/ping接口然后用浏览器直接访问http://localhost:3000/ping来验证服务器本身是否正常。如果/ping都打不开说明开发服务器自己挂了跟代理没关系。反过来如果/ping正常但带/api的请求异常问题就锁定在代理规则上。第三个技巧是善用浏览器的curl命令。在终端里用以下命令直接测试目标地址curl http://localhost:8080/api/user -H Origin: http://localhost:3000看返回的响应头里有没有允许跨域的字段。如果响应头缺失那就说明后端可能需要额外配置跨域策略光靠代理其实已经能通了。这类问题经常让我误以为代理没生效其实是后端自己也在做跨域限制。6.1 一个典型的调试实录我记忆里有次帮朋友排查代理问题现象很奇怪手机访问开发服务器能正常拿到数据但电脑浏览器却一直报跨域错误。两边访问的是同一个地址同一个网络为什么结果不一样后来发现电脑浏览器缓存了旧的Service Worker导致请求走了缓存一直没发到代理规则里。清除站点数据后马上恢复。这件事提醒我遇到代理问题时先想到“清理缓存”这个经典操作。类似的还有浏览器插件干扰。某些安全插件会拦截常见接口地址导致请求看起来是代理转发出去的但实际上被插件拦了。这种情况在Chrome的隐身模式里往往就消失了。所以代理配置调试一旦陷入困局先用隐身模式测试往往能排除一大批环境干扰因素。6.2 代理配置的最佳实践清单经过这么多年项目磨炼我总结了一套适合所有React项目的代理配置最佳实践。无论你是新项目还是老项目照着这套来基本上不会掉坑。我把这些实践分成三个层面配置层面优先使用setupProxy.js而不是package.json的proxy字段扩展性更好所有代理请求统一加/api前缀路径重写时保持一致性changeOrigin永远设置为true涉及HTTPS目标时设置secure: false并加注释说明原因工程层面用环境变量管理不同环境的代理目标地址代理配置里不要写死IP用相对路径并从环境变量读取定期用logLevel: debug验证代理目标是否符合预期运维层面修改代理配置后必须刷新浏览器缓存再测试在团队文档里写清楚每个代理规则对应哪个后端服务免得后人看不懂这个清单看着简单但真的执行到位能帮你省掉一大堆不必要的联调时间。我见过太多同事被代理问题折磨到怀疑人生最后发现只是少加了一个changeOrigin: true。自己在项目里配代理时最让我印象深刻的教训是永远不要假设配置项能一次到位。每写完一个代理规则我都会用不同路径多测几个请求确认路径重写、HTTP头、Cookie这几项都正常再继续下一个环节。有些问题光靠看配置是看不出来的必须实际请求一遍才能暴露。比如有一次我以为pathRewrite规则写对了结果请求发出的还是带着/api排查半天才发现正则里多了一个空格这种低级错误你很难在代码审查里发现真正请求时才会暴露。后来我习惯在pathRewrite里故意保留一段明文字符串做测试比如^/api: /test再通过日志打印出来的地址判断重写是否生效确认没问题再改成实际目标路径。代理这东西从原理到实践其实都不复杂复杂的是你面对的真实项目总有自己的乱七八糟的路径和多个服务互相调用。只要理解了“开发服务器替你转发请求”这个核心原理再掌握我今天说的这几个配置入口和调试手法你就已经能应对绝大多数场景了。后面遇到问题的时候记得先把请求日志打开看目标地址和实际路径基本就成功一半了。