1. 项目概述为什么React项目离不开代理配置做React开发的人几乎都会遇到同一个问题前端页面在本地跑得正欢一调后端接口就报跨域。尤其是用React官方脚手架Create React App以下简称CRA起步的项目npm start起的开发服务器默认跑在localhost:3000后端接口在localhost:8080或者别的端口两者只要协议、域名、端口任意一个不一致浏览器的同源策略就会直接给你拦下来。这时候代理Proxy配置就是最常用、最省事的解决办法。这里说的“代理配置”本质上是在开发服务器上加一层转发逻辑前端请求/api开头的接口时开发服务器收到后替浏览器把请求转发到目标后端服务器再把响应返回给前端。由于请求是从服务器发出去的不经过浏览器的同源策略检查跨域问题就绕过去了。整个过程对浏览器来说就像只请求了自己的开发服务器完全无感知。CRA脚手架本身内置了一套代理配置机制分为两种一种是简单的“全局代理”在package.json里加一个proxy字段就能搞定另一种是更灵活的“中间件代理”用http-proxy-middleware这个库在脚手架里注册自定义代理规则。这两种方案覆盖了从“只想快点跑通”到“需要精细化控制”的全部需求。这篇总结就是把两种方案都掰开揉碎讲清楚包括配置方法、背后的原理、踩坑记录和排查技巧适合刚入门React的开发者也适合项目里代理规则比较复杂的进阶使用者。2. 方案选型全局代理与中间件代理的取舍逻辑2.1 什么时候用package.json的proxy字段最简单的场景整个项目只需要把某一个固定前缀的请求转发到一个固定的后端地址。比如项目里所有接口都以/api开头后端地址就是http://localhost:8080那只需要在package.json里加一行{ name: my-app, proxy: http://localhost:8080 }加完这一行重启开发服务器前端代码里请求/api/user/list开发服务器就会自动转发到http://localhost:8080/api/user/list跨域直接消失。这个方案的最大优势就是零依赖、零额外代码不用安装任何npm包也不用创建额外的配置文件。但它的局限也很明显只能配置一个后端地址所有被代理的请求都指向同一个目标。而且它不支持自定义路径重写也就是说你不能把/api去掉再转发。假如后端接口的真实路径是/user/list没有/api前缀用这种方式就尴尬了——后端要求不带前缀前端请求带前缀直接转发过去后端路由匹配不上。另外这个字段只对开发环境的npm start生效对生产环境的构建结果没有影响所以别指望用它解决部署后的跨域。2.2 为什么要引入http-proxy-middleware当需求超过“单后端单前缀”的范围时全局代理就不够用了。比如前端同时要请求两个不同域名的后端服务/auth走认证中心/api走业务服务。请求代理到后端时需要去掉/api前缀因为后端接口本来就没有这个前缀。需要对特定路径的请求做额外处理比如修改请求头、处理WebSocket连接。要针对开发环境和测试环境切换不同的代理目标。这些问题靠proxy字段一个字符串解决不了必须用脚手架官方推荐的http-proxy-middleware。CRA在这方面的支持也算简单只要在src目录下新建一个setupProxy.js文件脚手架内置的启动脚本会自动读取这个文件并把它注册到开发服务器上。注意文件名和位置是约定俗成的不能改成别的名字也不能挪到src外面。从实现层面看setupProxy.js里的内容本质上是导出一个函数接收appExpress实例作为参数然后在app上注册中间件const { createProxyMiddleware } require(http-proxy-middleware); module.exports function (app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, }) ); };这样写一下效果跟全局代理差不多但后续可扩展性完全不同——你可以在中间件选项里加pathRewrite、onProxyReq、onProxyRes等配置实现更精细的控制。所以我的建议是如果只是临时跑通联调用package.json的proxy字段就够了如果项目结构稍微正式一点或者预感到未来接口地址会调整、会拆分子系统就直接上setupProxy.js省得后面来回改。2.3 两种方案的对比对比维度package.json 的 proxy 字段setupProxy.js http-proxy-middleware配置复杂度极低一行字符串需要安装依赖并写少量代码支持多目标服务器不支持支持可配多个前缀指向不同target支持路径重写不支持支持通过pathRewrite实现支持自定义请求处理不支持支持可拦截请求和响应适用场景快速原型、简单联调正式项目、复杂路由、多后端是否需要重启生效修改后需要修改后需要但新代码通常热载这个对比表格基本可以当作选型参考。实际项目中我见过把proxy字段和setupProxy.js同时使用的项目但不要这么做——两者的注册顺序不可控容易产生代理冲突。保持单一方案要么只用字段要么只用中间件。3. 核心细节解析代理配置的关键参数与执行机制3.1target、changeOrigin、pathRewrite到底影响了什么这三个参数是使用http-proxy-middleware时最容易纠结的地方逐个拆开看。target是代理目标服务器的完整地址写法上必须包含协议和端口号。比如http://10.10.1.2:3000这里有个常见误区如果目标地址是类似http://example.com/api这种带路径的请把路径去掉路径重写交给pathRewrite来做。因为target里的路径会和完整请求路径拼接拼出来的结果往往不是你想要的效果。我见过有人把target: http://localhost:8080/api写在配置里然后/api/user的请求变成了http://localhost:8080/api/api/user这种低级错误排查起来还挺费时间。changeOrigin这个参数值得多说一句。很多教程会告诉你“设成true”但背后的逻辑是后端服务器有时候会根据请求头里的Host字段来做虚拟主机路由或防爬虫校验。开发环境下浏览器发出的请求Host头是localhost:3000直接转发给后端后端的反代层或Nginx可能会因为不认识这个Host而拒绝请求。把changeOrigin: true设置上代理库转发时会把Host头改成target对应的域名让后端以为请求来自合法的源站地址。所以这个参数基本无脑开除非你明确知道后端不校验Host且有特殊用途比如某些后端拿着原始Host做逻辑判断否则一律置为true。pathRewrite是最能体现代理灵活性的参数本质就是一个“路径改写函数”。常见用法是把前端请求的/api前缀在转发前去掉createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: , }, })这样/api/user/list转发到目标服务器时就变成了/user/list后端不用为了配合前端特意加一层前缀映射。pathRewrite也支持用函数写更复杂的逻辑但从可读性角度用正则表达式替换更直观。注意^/api这个写法匹配的是路径开头如果你不小心写成/api它会匹配路径里所有出现的/api子串比如/user/apilist也会被误改应避免这种低级错误。3.2 代理发起时机静态资源与接口请求的区别代理不是把开发服务器收到的所有请求都转发出去它是有匹配条件的。中间件的第一个参数可以是字符串或者数组比如/api、[/api, /auth]只有路径以这些前缀开头的请求才会被代理处理。其他请求比如localhost:3000/static/js/main.js仍然由CRA的默认处理逻辑接手返回本地构建的文件。所以你在配置时要做到心里有数代理的匹配路径必须能精确覆盖所有需要访问后端的请求同时不能误伤静态资源请求。一个比较踏实的做法是约定所有后端接口请求统一带/api前缀然后代理只需要匹配这一个前缀。如果是老项目接口路径已经乱得没法统一了那就用数组或者正则表达式来匹配比如app.use([/api, /user, /order], createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, }))这种写法适合多个路径前缀指向同一个后端的情况。但匹配范围越大越要小心后端返回的HTML或者图片资源路径被误处理因为那些资源请求可能也是这几个前缀开头的。3.3setupProxy.js的加载时机与原理CRA的启动逻辑里react-scripts在启动开发服务器时会读取src/setupProxy.js并调用它。这个文件不是前端编译产物而是Node.js环境下的脚本所以文件里可以放心使用require不能使用ESModule的import除非你在文件名上用了特殊的类型扩展名。这里有个很重要的点setupProxy.js里注册的中间件是在整个开发服务器的中间件栈的靠前位置执行的也就是说它会先于CRA默认的静态资源响应逻辑执行。这也解释了为什么这个文件支持自定义处理逻辑因为它插入的位置非常早。从配置异常的排查角度来说如果你写了setupProxy.js但发现代理没生效先检查这个文件有没有被正确读取。验证方式很简单在文件里加一行console.log(setupProxy loaded)重启开发服务器看终端里有没有这行输出。没有输出说明文件名或位置不对有输出但代理还是不生效再去检查匹配规则和target。4. 实操过程从零配置一个React代理环境4.1 环境准备与依赖安装用CRA脚手架创建项目后第一步是安装http-proxy-middleware。注意版本兼容性CRA 4.x 及更新版本对应的react-scripts版本要求http-proxy-middleware的版本通常用1.x分支就够了。如果装成2.x虽然大部分API兼容但有少部分写法变了比如createProxyMiddleware的导入方式没变但内部选项结构有小调整。为了少踩坑我建议在项目里直接执行npm install http-proxy-middleware --save-dev为什么要装为开发依赖因为代理只服务于开发环境生产构建完全用不到放在dependencies里只会让npm install多下载一些没必要的包以及增加package-lock的体积。虽然影响不大但项目规范好一点依赖边界清晰一点后面维护的人会感谢你。装完之后在src目录下创建setupProxy.js。只要文件名叫这个CRA的启动脚本就会自动加载不需要额外到webpack.config.js里改任何东西。这个“约定大于配置”的设计是CRA为了保持项目结构简单而特意设定的很多人不知道就跑去改webpack配置白白增加了复杂度。4.2 一个能满足大多数场景的通用配置模板下面这份配置我实际用了很久覆盖了多后端、路径重写、请求头注入和超时控制几个常见需求直接抄过去改改参数就能用const { createProxyMiddleware } require(http-proxy-middleware); module.exports function (app) { // 业务接口去掉 /api 前缀后转发到后端服务 app.use( /api, createProxyMiddleware({ target: http://192.168.1.10:8080, changeOrigin: true, pathRewrite: { ^/api: }, timeout: 60000, proxyRequestTimeout: 60000, }) ); // 认证服务/auth 前缀直接透传 app.use( /auth, createProxyMiddleware({ target: http://auth.inner.svc:8081, changeOrigin: true, }) ); // 文件上传服务注入自定义Header并限制body大小 app.use( /upload, createProxyMiddleware({ target: http://upload.inner.svc:8082, changeOrigin: true, onProxyReq: (proxyReq, req, res) { if (req.headers[x-upload-token]) { proxyReq.setHeader(x-upload-token, req.headers[x-upload-token]); } }, }) ); };第一段是常规的接口代理第二段是直接透传第三段演示了如何在转发前把请求头摘出来塞给后端。实际项目中onProxyReq的用途还很多比如给请求追加签名参数、修改cookie、调试打印请求路径等。只要理解了“中间件在执行时可以同时操作请求对象和转发请求对象”这个原理很多定制需求都能在这里完成。4.3 修改配置后必须做的3个动作配置写好不等于生效有几步操作顺序错了会白忙活保存文件后重启开发服务器。setupProxy.js的读取发生在启动阶段不像其他业务代码那样支持热更新所以每次修改这个文件都要在终端里按CtrlC停掉npm start重新启动。清一下浏览器缓存。虽然代理本身和缓存没直接关系但开发服务器重启后经常会有旧的Service Worker或浏览器缓存干扰。稳妥起见打开无痕窗口测试。打开浏览器开发者工具看Network面板。重点看请求的实际地址——如果代理生效请求的“Name”列显示的仍然是localhost:3000/api/xxx但“Initiator”或者“Response Headers”里能看到目标服务器的信息。这里有一个更直观的判断方法如果请求显示出的状态码是200响应内容正常就不再是跨域错误如果控制台里还有“Access-Control-Allow-Origin”相关的报错说明请求根本没走代理。4.4 生产环境怎么办代理配置不生效的真相有一个新手特别容易踩的坑项目开发时代理配得好好的npm run build之后部署到服务器上接口全部报404或跨域。这不是代理失效而是生产构建根本不包含setupProxy.js里的代理逻辑。原因在前文说过——代理配置只注入到开发服务器里构建出来的静态文件是纯前端资源没有服务器运行时代理能力。生产环境解决跨域的正确思路是通过Nginx反向代理或者在部署平台上配置转发规则。比如在Nginx里location /api/ { proxy_pass http://backend-server:8080/; }这个配置的效果和开发环境里pathRewrite: { ^/api: }类似都会把/api去掉再转发给后端。如果你的项目要自己部署上线一定得在部署阶段想好这个环节别等到上线了才问“为什么我的代理没生效”。5. 常见问题与排查技巧实录5.1 代理虽然生效但请求一直返回502遇到502多半是目标服务器本身不可达或者返回了非正常的响应。排查顺序直接在浏览器地址栏访问target地址比如http://192.168.1.10:8080/health确认后端服务是否真的活着。查看开发服务器终端的报错信息通常会直接打印出ECONNREFUSED或ETIMEDOUT前者说明端口不对后者说明网络不通。检查本机防火墙或后端服务绑定的监听地址后端如果只监听127.0.0.1而代理转发用的是局域网IP也会连不上。一个很常见的场景后端服务在别人电脑上跑着前端要访问他的局域网IP但对方防火墙没放开就会一直502。所以项目联调时第一件事永远是确认网络互通而不是盯着一堆代理参数调来调去。5.2 请求头丢失或Authorization带不过去代理默认会转发大部分请求头但有些自定义头可能在开发服务器层面就被过滤了。如果你发现请求头少了可以在onProxyReq里手动补上。比如调试时发现后端要求必传的x-tenant-id没到可以这样排查和修复onProxyReq: (proxyReq, req, res) { if (!req.headers[x-tenant-id]) { proxyReq.setHeader(x-tenant-id, default-tenant); } }这里的逻辑是如果原始请求没带这个头就给转发请求补一个默认值。实际操作中还要注意大小写问题。HTTP头字段名大小写不敏感但http-proxy-middleware内部处理时部分版本对header名的大小写比较敏感。安全做法是在设置和读取时都统一用小写。5.3 路径重写后页面样式或图片加载失败这个问题的典型症状接口走代理正常了但页面上图片、CSS、JS资源加载出现404。原因通常是后端返回的HTML里的资源引用路径是相对路径或根路径比如img src/static/pic.png浏览器解析时把它当成了localhost:3000/static/pic.png而这个路径在开发服务器上不存在代理又没匹配到这个路径自然404。解决思路有两个方向一是让前端统一用带/api前缀的路径请求资源二是针对静态资源路径再加一条代理规则。前者更干净因为资源路径可控是前提后者是应急做法只能在开发环境救急。如果是生产环境这种问题更常见于部署了子路径的场景需要同步调整package.json里的homepage字段和路由的basename属于另一套问题了。5.4 WebSocket代理失败的排查http-proxy-middleware支持WebSocket代理只需要在选项里加ws: true。但CRA开发服务器的WebSocket协议和普通HTTP的代理行为有些差异。如果你在做即时通信功能发现WebSocket连接一直建立失败先确认两件事是否在代理配置里开启了ws: true。是否在前端代码里指定了WebSocket连接的路径而不是用默认的localhost:3000去连。确定这两点没问题后再用浏览器开发者工具的Network面板里看WS连接的状态。如果WS连接一直处于Pending或直接报错误多半是后端WebSocket服务的地址配置有问题在后端日志里能看到连接尝试记录。代理本身只是转发它不负责建立应用层的业务握手。5.5 多环境切换的配置技巧开发环境、测试环境、预发环境后端地址各不相同。每次手动改setupProxy.js里的target不仅麻烦还容易改错。比较好的做法是用环境变量控制const targetMap { dev: http://localhost:8080, test: http://test.api.example.com, prod: http://api.example.com, }; const env process.env.REACT_APP_PROXY_TARGET || dev; module.exports function (app) { app.use( /api, createProxyMiddleware({ target: targetMap[env], changeOrigin: true, pathRewrite: { ^/api: }, }) ); };然后在启动命令里指定环境REACT_APP_PROXY_TARGETtest npm start这样就不用来回改配置文件了。注意REACT_APP_开头的环境变量会被CRA自动注入到前端代码但这里是在Node环境中读取同样生效。这个做法适合团队协作配合.env文件可以做到不同开发者本地启动时自动选择对应的后端地址。5.6 配置代理后接口还是提示CORS错误这个问题的出现频率不低很多人配置了代理但页面控制台依旧报“CORS”。先说结论如果代理生效且请求确实转发成功响应头里一般不会携带Access-Control-Allow-Origin因为浏览器认为请求来自同源。所以当你看到CORS错误时先怀疑代理没有生效而不是后端没配CORS。具体验证方法打开Network面板找到出错的接口看它的“Request URL”。如果Request URL是http://localhost:3000/api/xxx说明前端代码里的请求路径没问题接下来看请求是否真的走了代理——可以在onProxyReq里打印一条日志比如onProxyReq: (proxyReq, req, res) { console.log(Proxying request:, req.originalUrl); }如果终端里没有打印说明这个请求压根没匹配上代理规则。再回头检查匹配路径写没写错或者请求路径是不是前缀不匹配。80%的“配置了代理还是报跨域”最后都归结为代理规则没配上而不是别的玄学问题。6. 实操心得与经验总结在代理配置这件事上我踩过不少坑也帮别人排查过很多次问题总结下来就一句话代理的本质是开发服务器替浏览器做了一次转发理解这一点很多疑问都会迎刃而解。如果只看操作层面我的建议是直接使用setupProxy.js方案哪怕只是简单代理一个后端。原因在于这个方案可扩展性极强未来不管是要加路径重写、多目标后端还是加自定义请求头都只需要改动一个文件而不是把package.json里的proxy字段去掉重来。等到项目复杂度上来再迁移涉及面会更广没必要为了省一分钟配置时间留下技术债。另一个值得分享的经验是代理配置要尽早统一规范。如果团队里所有人都各自配各自的临时加一条路径规则直接堆在setupProxy.js里文件很快就会变得不可读。我自己习惯用注释把代理规则分块并标明每个规则对应的后端系统这样其他人接手时不用靠猜。还有一个小技巧把后端提供的接口路径前缀固定下来比如所有接口都加/api前缀这在前后端联调阶段能省下大量沟通成本——不是技术上解决不了而是约定远比配置重要。最后再提一个平时不太会注意的细节代理配置影响的是开发环境所以一旦你怀疑“为什么本地好了上线就坏”不要浪费时间在代理配置上应该直接去看部署环境的反向代理配置。开发环境的代理是整个开发体验中很小的一环但搞懂了它很多相关概念同源策略、请求头、Nginx转发都会自然而然地串起来这也是我把这些内容总结成文的初衷。
1. 项目概述为什么React项目离不开代理配置做React开发的人几乎都会遇到同一个问题前端页面在本地跑得正欢一调后端接口就报跨域。尤其是用React官方脚手架Create React App以下简称CRA起步的项目npm start起的开发服务器默认跑在localhost:3000后端接口在localhost:8080或者别的端口两者只要协议、域名、端口任意一个不一致浏览器的同源策略就会直接给你拦下来。这时候代理Proxy配置就是最常用、最省事的解决办法。这里说的“代理配置”本质上是在开发服务器上加一层转发逻辑前端请求/api开头的接口时开发服务器收到后替浏览器把请求转发到目标后端服务器再把响应返回给前端。由于请求是从服务器发出去的不经过浏览器的同源策略检查跨域问题就绕过去了。整个过程对浏览器来说就像只请求了自己的开发服务器完全无感知。CRA脚手架本身内置了一套代理配置机制分为两种一种是简单的“全局代理”在package.json里加一个proxy字段就能搞定另一种是更灵活的“中间件代理”用http-proxy-middleware这个库在脚手架里注册自定义代理规则。这两种方案覆盖了从“只想快点跑通”到“需要精细化控制”的全部需求。这篇总结就是把两种方案都掰开揉碎讲清楚包括配置方法、背后的原理、踩坑记录和排查技巧适合刚入门React的开发者也适合项目里代理规则比较复杂的进阶使用者。2. 方案选型全局代理与中间件代理的取舍逻辑2.1 什么时候用package.json的proxy字段最简单的场景整个项目只需要把某一个固定前缀的请求转发到一个固定的后端地址。比如项目里所有接口都以/api开头后端地址就是http://localhost:8080那只需要在package.json里加一行{ name: my-app, proxy: http://localhost:8080 }加完这一行重启开发服务器前端代码里请求/api/user/list开发服务器就会自动转发到http://localhost:8080/api/user/list跨域直接消失。这个方案的最大优势就是零依赖、零额外代码不用安装任何npm包也不用创建额外的配置文件。但它的局限也很明显只能配置一个后端地址所有被代理的请求都指向同一个目标。而且它不支持自定义路径重写也就是说你不能把/api去掉再转发。假如后端接口的真实路径是/user/list没有/api前缀用这种方式就尴尬了——后端要求不带前缀前端请求带前缀直接转发过去后端路由匹配不上。另外这个字段只对开发环境的npm start生效对生产环境的构建结果没有影响所以别指望用它解决部署后的跨域。2.2 为什么要引入http-proxy-middleware当需求超过“单后端单前缀”的范围时全局代理就不够用了。比如前端同时要请求两个不同域名的后端服务/auth走认证中心/api走业务服务。请求代理到后端时需要去掉/api前缀因为后端接口本来就没有这个前缀。需要对特定路径的请求做额外处理比如修改请求头、处理WebSocket连接。要针对开发环境和测试环境切换不同的代理目标。这些问题靠proxy字段一个字符串解决不了必须用脚手架官方推荐的http-proxy-middleware。CRA在这方面的支持也算简单只要在src目录下新建一个setupProxy.js文件脚手架内置的启动脚本会自动读取这个文件并把它注册到开发服务器上。注意文件名和位置是约定俗成的不能改成别的名字也不能挪到src外面。从实现层面看setupProxy.js里的内容本质上是导出一个函数接收appExpress实例作为参数然后在app上注册中间件const { createProxyMiddleware } require(http-proxy-middleware); module.exports function (app) { app.use( /api, createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, }) ); };这样写一下效果跟全局代理差不多但后续可扩展性完全不同——你可以在中间件选项里加pathRewrite、onProxyReq、onProxyRes等配置实现更精细的控制。所以我的建议是如果只是临时跑通联调用package.json的proxy字段就够了如果项目结构稍微正式一点或者预感到未来接口地址会调整、会拆分子系统就直接上setupProxy.js省得后面来回改。2.3 两种方案的对比对比维度package.json 的 proxy 字段setupProxy.js http-proxy-middleware配置复杂度极低一行字符串需要安装依赖并写少量代码支持多目标服务器不支持支持可配多个前缀指向不同target支持路径重写不支持支持通过pathRewrite实现支持自定义请求处理不支持支持可拦截请求和响应适用场景快速原型、简单联调正式项目、复杂路由、多后端是否需要重启生效修改后需要修改后需要但新代码通常热载这个对比表格基本可以当作选型参考。实际项目中我见过把proxy字段和setupProxy.js同时使用的项目但不要这么做——两者的注册顺序不可控容易产生代理冲突。保持单一方案要么只用字段要么只用中间件。3. 核心细节解析代理配置的关键参数与执行机制3.1target、changeOrigin、pathRewrite到底影响了什么这三个参数是使用http-proxy-middleware时最容易纠结的地方逐个拆开看。target是代理目标服务器的完整地址写法上必须包含协议和端口号。比如http://10.10.1.2:3000这里有个常见误区如果目标地址是类似http://example.com/api这种带路径的请把路径去掉路径重写交给pathRewrite来做。因为target里的路径会和完整请求路径拼接拼出来的结果往往不是你想要的效果。我见过有人把target: http://localhost:8080/api写在配置里然后/api/user的请求变成了http://localhost:8080/api/api/user这种低级错误排查起来还挺费时间。changeOrigin这个参数值得多说一句。很多教程会告诉你“设成true”但背后的逻辑是后端服务器有时候会根据请求头里的Host字段来做虚拟主机路由或防爬虫校验。开发环境下浏览器发出的请求Host头是localhost:3000直接转发给后端后端的反代层或Nginx可能会因为不认识这个Host而拒绝请求。把changeOrigin: true设置上代理库转发时会把Host头改成target对应的域名让后端以为请求来自合法的源站地址。所以这个参数基本无脑开除非你明确知道后端不校验Host且有特殊用途比如某些后端拿着原始Host做逻辑判断否则一律置为true。pathRewrite是最能体现代理灵活性的参数本质就是一个“路径改写函数”。常见用法是把前端请求的/api前缀在转发前去掉createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, pathRewrite: { ^/api: , }, })这样/api/user/list转发到目标服务器时就变成了/user/list后端不用为了配合前端特意加一层前缀映射。pathRewrite也支持用函数写更复杂的逻辑但从可读性角度用正则表达式替换更直观。注意^/api这个写法匹配的是路径开头如果你不小心写成/api它会匹配路径里所有出现的/api子串比如/user/apilist也会被误改应避免这种低级错误。3.2 代理发起时机静态资源与接口请求的区别代理不是把开发服务器收到的所有请求都转发出去它是有匹配条件的。中间件的第一个参数可以是字符串或者数组比如/api、[/api, /auth]只有路径以这些前缀开头的请求才会被代理处理。其他请求比如localhost:3000/static/js/main.js仍然由CRA的默认处理逻辑接手返回本地构建的文件。所以你在配置时要做到心里有数代理的匹配路径必须能精确覆盖所有需要访问后端的请求同时不能误伤静态资源请求。一个比较踏实的做法是约定所有后端接口请求统一带/api前缀然后代理只需要匹配这一个前缀。如果是老项目接口路径已经乱得没法统一了那就用数组或者正则表达式来匹配比如app.use([/api, /user, /order], createProxyMiddleware({ target: http://localhost:8080, changeOrigin: true, }))这种写法适合多个路径前缀指向同一个后端的情况。但匹配范围越大越要小心后端返回的HTML或者图片资源路径被误处理因为那些资源请求可能也是这几个前缀开头的。3.3setupProxy.js的加载时机与原理CRA的启动逻辑里react-scripts在启动开发服务器时会读取src/setupProxy.js并调用它。这个文件不是前端编译产物而是Node.js环境下的脚本所以文件里可以放心使用require不能使用ESModule的import除非你在文件名上用了特殊的类型扩展名。这里有个很重要的点setupProxy.js里注册的中间件是在整个开发服务器的中间件栈的靠前位置执行的也就是说它会先于CRA默认的静态资源响应逻辑执行。这也解释了为什么这个文件支持自定义处理逻辑因为它插入的位置非常早。从配置异常的排查角度来说如果你写了setupProxy.js但发现代理没生效先检查这个文件有没有被正确读取。验证方式很简单在文件里加一行console.log(setupProxy loaded)重启开发服务器看终端里有没有这行输出。没有输出说明文件名或位置不对有输出但代理还是不生效再去检查匹配规则和target。4. 实操过程从零配置一个React代理环境4.1 环境准备与依赖安装用CRA脚手架创建项目后第一步是安装http-proxy-middleware。注意版本兼容性CRA 4.x 及更新版本对应的react-scripts版本要求http-proxy-middleware的版本通常用1.x分支就够了。如果装成2.x虽然大部分API兼容但有少部分写法变了比如createProxyMiddleware的导入方式没变但内部选项结构有小调整。为了少踩坑我建议在项目里直接执行npm install http-proxy-middleware --save-dev为什么要装为开发依赖因为代理只服务于开发环境生产构建完全用不到放在dependencies里只会让npm install多下载一些没必要的包以及增加package-lock的体积。虽然影响不大但项目规范好一点依赖边界清晰一点后面维护的人会感谢你。装完之后在src目录下创建setupProxy.js。只要文件名叫这个CRA的启动脚本就会自动加载不需要额外到webpack.config.js里改任何东西。这个“约定大于配置”的设计是CRA为了保持项目结构简单而特意设定的很多人不知道就跑去改webpack配置白白增加了复杂度。4.2 一个能满足大多数场景的通用配置模板下面这份配置我实际用了很久覆盖了多后端、路径重写、请求头注入和超时控制几个常见需求直接抄过去改改参数就能用const { createProxyMiddleware } require(http-proxy-middleware); module.exports function (app) { // 业务接口去掉 /api 前缀后转发到后端服务 app.use( /api, createProxyMiddleware({ target: http://192.168.1.10:8080, changeOrigin: true, pathRewrite: { ^/api: }, timeout: 60000, proxyRequestTimeout: 60000, }) ); // 认证服务/auth 前缀直接透传 app.use( /auth, createProxyMiddleware({ target: http://auth.inner.svc:8081, changeOrigin: true, }) ); // 文件上传服务注入自定义Header并限制body大小 app.use( /upload, createProxyMiddleware({ target: http://upload.inner.svc:8082, changeOrigin: true, onProxyReq: (proxyReq, req, res) { if (req.headers[x-upload-token]) { proxyReq.setHeader(x-upload-token, req.headers[x-upload-token]); } }, }) ); };第一段是常规的接口代理第二段是直接透传第三段演示了如何在转发前把请求头摘出来塞给后端。实际项目中onProxyReq的用途还很多比如给请求追加签名参数、修改cookie、调试打印请求路径等。只要理解了“中间件在执行时可以同时操作请求对象和转发请求对象”这个原理很多定制需求都能在这里完成。4.3 修改配置后必须做的3个动作配置写好不等于生效有几步操作顺序错了会白忙活保存文件后重启开发服务器。setupProxy.js的读取发生在启动阶段不像其他业务代码那样支持热更新所以每次修改这个文件都要在终端里按CtrlC停掉npm start重新启动。清一下浏览器缓存。虽然代理本身和缓存没直接关系但开发服务器重启后经常会有旧的Service Worker或浏览器缓存干扰。稳妥起见打开无痕窗口测试。打开浏览器开发者工具看Network面板。重点看请求的实际地址——如果代理生效请求的“Name”列显示的仍然是localhost:3000/api/xxx但“Initiator”或者“Response Headers”里能看到目标服务器的信息。这里有一个更直观的判断方法如果请求显示出的状态码是200响应内容正常就不再是跨域错误如果控制台里还有“Access-Control-Allow-Origin”相关的报错说明请求根本没走代理。4.4 生产环境怎么办代理配置不生效的真相有一个新手特别容易踩的坑项目开发时代理配得好好的npm run build之后部署到服务器上接口全部报404或跨域。这不是代理失效而是生产构建根本不包含setupProxy.js里的代理逻辑。原因在前文说过——代理配置只注入到开发服务器里构建出来的静态文件是纯前端资源没有服务器运行时代理能力。生产环境解决跨域的正确思路是通过Nginx反向代理或者在部署平台上配置转发规则。比如在Nginx里location /api/ { proxy_pass http://backend-server:8080/; }这个配置的效果和开发环境里pathRewrite: { ^/api: }类似都会把/api去掉再转发给后端。如果你的项目要自己部署上线一定得在部署阶段想好这个环节别等到上线了才问“为什么我的代理没生效”。5. 常见问题与排查技巧实录5.1 代理虽然生效但请求一直返回502遇到502多半是目标服务器本身不可达或者返回了非正常的响应。排查顺序直接在浏览器地址栏访问target地址比如http://192.168.1.10:8080/health确认后端服务是否真的活着。查看开发服务器终端的报错信息通常会直接打印出ECONNREFUSED或ETIMEDOUT前者说明端口不对后者说明网络不通。检查本机防火墙或后端服务绑定的监听地址后端如果只监听127.0.0.1而代理转发用的是局域网IP也会连不上。一个很常见的场景后端服务在别人电脑上跑着前端要访问他的局域网IP但对方防火墙没放开就会一直502。所以项目联调时第一件事永远是确认网络互通而不是盯着一堆代理参数调来调去。5.2 请求头丢失或Authorization带不过去代理默认会转发大部分请求头但有些自定义头可能在开发服务器层面就被过滤了。如果你发现请求头少了可以在onProxyReq里手动补上。比如调试时发现后端要求必传的x-tenant-id没到可以这样排查和修复onProxyReq: (proxyReq, req, res) { if (!req.headers[x-tenant-id]) { proxyReq.setHeader(x-tenant-id, default-tenant); } }这里的逻辑是如果原始请求没带这个头就给转发请求补一个默认值。实际操作中还要注意大小写问题。HTTP头字段名大小写不敏感但http-proxy-middleware内部处理时部分版本对header名的大小写比较敏感。安全做法是在设置和读取时都统一用小写。5.3 路径重写后页面样式或图片加载失败这个问题的典型症状接口走代理正常了但页面上图片、CSS、JS资源加载出现404。原因通常是后端返回的HTML里的资源引用路径是相对路径或根路径比如img src/static/pic.png浏览器解析时把它当成了localhost:3000/static/pic.png而这个路径在开发服务器上不存在代理又没匹配到这个路径自然404。解决思路有两个方向一是让前端统一用带/api前缀的路径请求资源二是针对静态资源路径再加一条代理规则。前者更干净因为资源路径可控是前提后者是应急做法只能在开发环境救急。如果是生产环境这种问题更常见于部署了子路径的场景需要同步调整package.json里的homepage字段和路由的basename属于另一套问题了。5.4 WebSocket代理失败的排查http-proxy-middleware支持WebSocket代理只需要在选项里加ws: true。但CRA开发服务器的WebSocket协议和普通HTTP的代理行为有些差异。如果你在做即时通信功能发现WebSocket连接一直建立失败先确认两件事是否在代理配置里开启了ws: true。是否在前端代码里指定了WebSocket连接的路径而不是用默认的localhost:3000去连。确定这两点没问题后再用浏览器开发者工具的Network面板里看WS连接的状态。如果WS连接一直处于Pending或直接报错误多半是后端WebSocket服务的地址配置有问题在后端日志里能看到连接尝试记录。代理本身只是转发它不负责建立应用层的业务握手。5.5 多环境切换的配置技巧开发环境、测试环境、预发环境后端地址各不相同。每次手动改setupProxy.js里的target不仅麻烦还容易改错。比较好的做法是用环境变量控制const targetMap { dev: http://localhost:8080, test: http://test.api.example.com, prod: http://api.example.com, }; const env process.env.REACT_APP_PROXY_TARGET || dev; module.exports function (app) { app.use( /api, createProxyMiddleware({ target: targetMap[env], changeOrigin: true, pathRewrite: { ^/api: }, }) ); };然后在启动命令里指定环境REACT_APP_PROXY_TARGETtest npm start这样就不用来回改配置文件了。注意REACT_APP_开头的环境变量会被CRA自动注入到前端代码但这里是在Node环境中读取同样生效。这个做法适合团队协作配合.env文件可以做到不同开发者本地启动时自动选择对应的后端地址。5.6 配置代理后接口还是提示CORS错误这个问题的出现频率不低很多人配置了代理但页面控制台依旧报“CORS”。先说结论如果代理生效且请求确实转发成功响应头里一般不会携带Access-Control-Allow-Origin因为浏览器认为请求来自同源。所以当你看到CORS错误时先怀疑代理没有生效而不是后端没配CORS。具体验证方法打开Network面板找到出错的接口看它的“Request URL”。如果Request URL是http://localhost:3000/api/xxx说明前端代码里的请求路径没问题接下来看请求是否真的走了代理——可以在onProxyReq里打印一条日志比如onProxyReq: (proxyReq, req, res) { console.log(Proxying request:, req.originalUrl); }如果终端里没有打印说明这个请求压根没匹配上代理规则。再回头检查匹配路径写没写错或者请求路径是不是前缀不匹配。80%的“配置了代理还是报跨域”最后都归结为代理规则没配上而不是别的玄学问题。6. 实操心得与经验总结在代理配置这件事上我踩过不少坑也帮别人排查过很多次问题总结下来就一句话代理的本质是开发服务器替浏览器做了一次转发理解这一点很多疑问都会迎刃而解。如果只看操作层面我的建议是直接使用setupProxy.js方案哪怕只是简单代理一个后端。原因在于这个方案可扩展性极强未来不管是要加路径重写、多目标后端还是加自定义请求头都只需要改动一个文件而不是把package.json里的proxy字段去掉重来。等到项目复杂度上来再迁移涉及面会更广没必要为了省一分钟配置时间留下技术债。另一个值得分享的经验是代理配置要尽早统一规范。如果团队里所有人都各自配各自的临时加一条路径规则直接堆在setupProxy.js里文件很快就会变得不可读。我自己习惯用注释把代理规则分块并标明每个规则对应的后端系统这样其他人接手时不用靠猜。还有一个小技巧把后端提供的接口路径前缀固定下来比如所有接口都加/api前缀这在前后端联调阶段能省下大量沟通成本——不是技术上解决不了而是约定远比配置重要。最后再提一个平时不太会注意的细节代理配置影响的是开发环境所以一旦你怀疑“为什么本地好了上线就坏”不要浪费时间在代理配置上应该直接去看部署环境的反向代理配置。开发环境的代理是整个开发体验中很小的一环但搞懂了它很多相关概念同源策略、请求头、Nginx转发都会自然而然地串起来这也是我把这些内容总结成文的初衷。
