将 React 应用进行 Docker 化，核心目标是在保持开发体验不变的前提下，产出体积小、启动快、易于分发的镜像。许多团队在初期直接基于 node 镜像运行 npm start，但这不仅包含完整的编译工具链，还暴露了源代码与开发服务器，并不适合生产。合理的做法是通过多阶段构建分离编译与运行环境。
为什么需要多阶段构建
React 应用在生产环境只需要静态的 HTML、JS 和 CSS 文件，并不需要 Node 运行时来编译 JSX 或打包模块。如果采用单一镜像，最终容器里会保留 webpack、babel、数以万计的依赖包，这些内容在浏览器端完全用不到，却显著增加了镜像体积与攻击面。
多阶段构建允许在一个 Dockerfile 中定义多个 FROM 指令，每个阶段可以使用不同的基础镜像。前一个阶段负责安装依赖与执行构建，后一个阶段从一个极简的 Web 服务器镜像（如 nginx:alpine）复制构建产物。这样最终镜像里只有 Nginx 和静态文件，通常能控制在 30MB 到 50MB 之间。
编写基础 Dockerfile
下面给出一个典型的 React 多阶段构建示例，第一阶段基于 node:18-alpine 完成安装与打包，第二阶段使用 nginx 提供静态服务。
# 第一阶段：构建 FROM node:18-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build # 第二阶段：运行 FROM nginx:alpine COPY --from=build /app/build /usr/share/nginx/html EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]
上述代码中，npm ci 比 npm install 更适合 CI 环境，因为它严格按照锁文件安装，速度更快且可复现。COPY --from=build 只把 build 目录复制出来，node_modules 不会被带入最终镜像。
需要注意，若项目使用了环境变量注入（如 REACT_APP_API_URL），应在构建阶段通过 ARG 或 ENV 传入，因为 React 的这类变量在编译时就被写死进 JS 文件，运行时再改环境变量是无效的。
使用 .dockerignore 提升效率
Docker 在发送构建上下文时会把当前目录所有文件传给守护进程，如果不加忽略，本地 node_modules、.git、日志都会拖慢构建。创建 .dockerignore 文件与 .gitignore 类似，可大幅减少上下文体积。
node_modules build .git npm-debug.log Dockerfile .dockerignore
忽略 node_modules 尤为重要，因为我们在镜像内会重新执行 npm ci，本地包既不需要也不该被覆盖进容器。忽略 build 目录则避免把上一次产物又拷贝回去，造成混淆。
通过构建参数区分环境
有时测试环境与生产环境的 API 地址不同，可以在 docker build 时传入参数，并在构建阶段赋值给 React 环境变量。
FROM node:18-alpine AS build ARG API_URL ENV REACT_APP_API_URL=$API_URL WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci COPY . . RUN npm run build
构建命令形如 docker build --build-arg API_URL=https://api.ipipp.com -t react-app:test .。这样无需改动代码即可切换后端地址。但要记住，这些变量会出现在最终前端代码中，绝不能用来传递数据库密码等敏感信息。
常见误区与优化建议
一个常见错误是在 nginx 阶段未配置 SPA 路由回退。React 使用 BrowserRouter 时，用户直接访问子路由会 404，需要在 Nginx 配置里把未知路径指回 index.html。
server {
listen 80;
root /usr/share/nginx/html;
location / {
try_files $uri /index.html;
}
}
将该配置通过 COPY 覆盖默认配置即可。另外，可结合 CI 缓存 node_modules 层进一步加速，但多阶段构建本身已解决了镜像体积的核心矛盾。掌握上述流程后，React 应用的 Docker 化既安全又轻量，能无缝接入 Kubernetes 等编排系统。