如何在Docker容器的Create React App中不重建动态修改API URL

这个问题问到点子上了——谁也不想每次切换环境都重新构建镜像对吧？我在多个React + Docker项目里实践过几种方案，下面分享几个无需重新构建就能在不同环境运行的靠谱方法：

1. 运行时注入环境变量到静态配置文件 #

这是最通用的方案，核心思路是把API URL这类配置从构建时硬编码改成运行时动态注入：

• 第一步：在项目的public目录下创建一个配置模板文件config.template.js：

  window.appConfig = {
    API_URL: "${API_URL}"
  };
  

• 第二步：在React应用里直接读取这个全局变量，比如在API请求封装里：

  const apiBaseUrl = window.appConfig.API_URL || "https://default-api.example.com";
  
  export const fetchData = async () => {
    const response = await fetch(`${apiBaseUrl}/data`);
    return response.json();
  };
  

• 第三步：配置Docker的entrypoint脚本，在容器启动时用环境变量替换模板里的占位符：
  创建entrypoint.sh脚本：

  #!/bin/sh
  # 替换模板变量，生成最终的配置文件
  envsubst < /usr/share/nginx/html/config.template.js > /usr/share/nginx/html/config.js
  # 执行原本的容器启动命令（比如启动Nginx）
  exec "$@"
  

• 第四步：编写Dockerfile，用Nginx作为生产环境的服务器：

  # 构建阶段
  FROM node:18-alpine as builder
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  RUN npm run build
  
  # 生产阶段
  FROM nginx:alpine
  # 复制构建好的静态文件
  COPY --from=builder /app/build /usr/share/nginx/html
  # 复制配置模板和启动脚本
  COPY public/config.template.js /usr/share/nginx/html/config.template.js
  COPY entrypoint.sh /entrypoint.sh
  # 给脚本添加执行权限
  RUN chmod +x /entrypoint.sh
  # 设置启动入口
  ENTRYPOINT ["/entrypoint.sh"]
  CMD ["nginx", "-g", "daemon off;"]
  

这样启动容器时，只需要传入环境变量就能切换API地址：

docker run -e API_URL=https://dev-api.example.com your-app-image
docker run -e API_URL=https://prod-api.example.com your-app-image

2. 通过Nginx反向代理动态配置API地址 #

如果你的前端和API可以通过域名或路径代理，这个方案更简洁，前端代码完全不用关心API地址：

• 第一步：创建Nginx配置模板nginx.conf.template：

  server {
    listen 80;
    root /usr/share/nginx/html;
    index index.html;
  
    # 把所有/api开头的请求代理到指定的API地址
    location /api/ {
      proxy_pass ${API_URL}/;
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
    }
  
    # 处理React的SPA路由
    location / {
      try_files $uri $uri/ /index.html;
    }
  }
  

• 第二步：修改Dockerfile，替换成这个Nginx模板和对应的entrypoint脚本：

  FROM node:18-alpine as builder
  WORKDIR /app
  COPY package*.json ./
  RUN npm install
  COPY . .
  RUN npm run build
  
  FROM nginx:alpine
  COPY --from=builder /app/build /usr/share/nginx/html
  COPY nginx.conf.template /etc/nginx/conf.d/default.conf.template
  COPY entrypoint.sh /entrypoint.sh
  RUN chmod +x /entrypoint.sh
  ENTRYPOINT ["/entrypoint.sh"]
  CMD ["nginx", "-g", "daemon off;"]
  

• 第三步：修改entrypoint.sh，替换Nginx配置里的占位符：

  #!/bin/sh
  envsubst < /etc/nginx/conf.d/default.conf.template > /etc/nginx/conf.d/default.conf
  exec "$@"
  

这时前端请求直接用/api/作为前缀就行，比如：

export const fetchData = async () => {
  const response = await fetch("/api/data");
  return response.json();
};

启动容器时指定API地址：

docker run -e API_URL=https://dev-api.example.com your-app-image

方案选择建议 #

• 如果你的API需要跨域访问，或者前端必须直接使用完整的API地址，选第一种方案；
• 如果可以通过Nginx代理统一管理API请求，第二种方案更干净，前端代码不需要任何环境变量相关的逻辑。

这两种方案都能实现“一次构建，多环境运行”的目标，我在生产环境都用过，稳定性没问题。

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