使用Craco的React应用部署到GCP Cloud Run出现React Refresh生产包错误

报错含义 #

这个错误表示你的生产打包产物中错误混入了仅用于开发环境的React Refresh运行时代码。React Refresh是React生态提供的开发阶段热更新工具，作用是本地开发时修改代码后不用刷新页面就能更新UI，本身就设计为不允许出现在生产环境的代码包中，所以运行时会主动抛出这个错误。

根因说明 #

你本地运行正常是因为本地执行的是craco start启动的开发服务，本来就需要加载React Refresh；而部署到Cloud Run时构建过程误判了环境类型，导致构建工具把开发态的依赖也打进了生产包。

解决步骤 #

• 第一步：修改Dockerfile，构建阶段显式指定生产环境变量
  修改你的Dockerfile构建段代码，添加NODE_ENV声明，避免构建工具默认读取到开发环境配置：

# build environment
FROM node:14-alpine as react-build
WORKDIR /app
COPY . ./
RUN yarn
# 新增以下行，强制指定生产环境
ENV NODE_ENV=production
RUN yarn build

# server environment
FROM nginx:alpine
COPY nginx.conf /etc/nginx/conf.d/configfile.template

COPY --from=react-build /app/build /usr/share/nginx/html

ENV PORT 8080
ENV HOST 0.0.0.0
EXPOSE 8080
CMD sh -c "envsubst '\$PORT' < /etc/nginx/conf.d/configfile.template > /etc/nginx/conf.d/default.conf && nginx -g 'daemon off;'"

• 第二步：（可选，第一步无效时执行）更新Craco配置，显式禁用生产环境热重载
  如果修改Dockerfile后问题依旧存在，说明你的Craco配置默认开启了全环境的热重载支持，更新craco.config.js如下：

const CracoAlias = require("craco-alias");

module.exports = {
  // 新增配置：仅开发环境启用React Refresh相关能力
  babel: {
    plugins: process.env.NODE_ENV === "development" ? ["react-refresh/babel"] : [],
  },
  plugins: [
    {
      plugin: CracoAlias,
      options: {
        source: "options",
        baseUrl: "./",
        aliases: {
          "@mui/styled-engine": "./node_modules/@mui/styled-engine-sc",
        },
      },
    },
  ],
};

• 第三步：清理缓存重新部署
  GCP远程构建会默认复用历史构建缓存，你可以在部署时添加--no-cache参数禁用缓存，确保所有配置修改都能生效。

内容的提问来源于stack exchange，提问作者Bill Software Engineer