react-scripts未加载setupProxy.js问题求助（CRA+craco环境）

问题背景 #

使用react-scripts@5.0.1创建的CRA项目，搭配Craco，原package.json的proxy配置启动失败，按照官方文档创建src/setupProxy.js后，文件完全未被加载（无日志输出、抛错不影响启动、调试确认未执行）。调用/api接口时返回React应用的HTML页面，代理完全未生效。尝试在craco.config.ts中配置devServer（根属性、Webpack子属性两种方式）均无效，目前通过webpack.DefinePlugin做临时替换，但并非理想方案。

相关配置文件：

setupProxy.js #

require('colors');
const { createProxyMiddleware } = require('http-proxy-middleware');

console.log('*****
setupProxy.js called
*****'.rainbow);

module.exports = function (app) {
  console.log('*****
Setting up proxy
*****'.rainbow);
  app.use(
    '/api',
    createProxyMiddleware({
      target: 'https://dev.spellingbeehints.app:4000',
      changeOrigin: true,
    })
  );
};

.env #

HTTPS=true
SSL_CRT_FILE=./certs/cert.pem
SSL_KEY_FILE=./certs/privkey.pem
HOST=dev.example.com

分步解决方案 #

1. 严格检查setupProxy.js的位置与命名 #

• 必须放置在项目src目录下，路径为src/setupProxy.js，不能放在项目根目录或其他子文件夹。
• 文件名必须为setupProxy.js（react-scripts默认仅自动识别.js后缀，使用TS需额外配置），大小写严格匹配。

2. 确保http-proxy-middleware版本兼容 #

react-scripts@5.0.1依赖http-proxy-middleware v2.x版本，若安装的是v1.x会导致导入或执行失败：

• 执行以下命令检查版本：

  npm list http-proxy-middleware
  

• 若版本为v1.x，卸载后重装v2.x：

  npm uninstall http-proxy-middleware
  npm install http-proxy-middleware@^2.0.6
  

3. 修复Craco中的代理配置 #

使用Craco时，setupProxy.js可能被Craco的配置覆盖，需在craco.config.ts中正确配置devServer代理：

import type { CracoConfig } from '@craco/craco';

const config: CracoConfig = {
  devServer: {
    proxy: {
      '/api': {
        target: 'https://dev.spellingbeehints.app:4000',
        changeOrigin: true,
        secure: false, // 目标为自签HTTPS证书时必须添加，跳过SSL验证
      },
    },
  },
};

export default config;

注意：不要同时保留setupProxy.js和Craco中的代理配置，避免冲突。

4. 排查.env配置的影响 #

开启HTTPS和自定义HOST可能导致代理异常：

• 若目标服务器使用自签HTTPS证书，必须在代理配置中添加secure: false，否则会因SSL验证失败导致代理失效。
• 自定义HOST需确保请求的/api路径是相对于当前HOST的，未被React路由错误拦截。

5. 清理缓存并重启项目 #

旧缓存可能导致配置不生效：

• 执行命令重置CRA缓存：

  npm start -- --reset-cache
  

• 完全关闭项目进程后重新启动，避免残留进程加载旧配置。

6. 兜底方案：手动搭建Express代理服务器 #

若以上方案均无效，可手动创建Express服务器代替CRA的devServer：

// 项目根目录/server.js
const express = require('express');
const { createProxyMiddleware } = require('http-proxy-middleware');
const path = require('path');

const app = express();

// 配置API代理
app.use('/api', createProxyMiddleware({
  target: 'https://dev.spellingbeehints.app:4000',
  changeOrigin: true,
  secure: false,
}));

// 托管React静态文件与路由
app.use(express.static(path.join(__dirname, 'build')));
app.get('*', (req, res) => {
  res.sendFile(path.join(__dirname, 'build', 'index.html'));
});

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`服务器运行在端口 ${PORT}`);
});

修改package.json的启动脚本：

"scripts": {
  "build": "react-scripts build",
  "start": "npm run build && node server.js",
  "dev": "nodemon server-dev.js" // 安装nodemon实现开发热重载
}

内容的提问来源于stack exchange，提问作者dx_over_dt