React项目Docker部署实战：从Dockerfile到Nginx托管

很多前端同学对 Docker 的态度一直是“听说过、大概知道、但自己没真正上手过”。项目做完往上一扔部署是后端或者运维的事。但真到了自己独立负责一个项目或者要交付一个可复现的环境时不懂 Docker 会非常被动。这篇就用一个 React 项目走完整条路从安装 Docker 开始到写出 Dockerfile、用 Nginx 托管静态文件、再用 docker-compose 一键拉起整个环境过程中会把我踩过的坑、验证过的做法、排查问题的思路全部写出来保证你照着走能跑通。1. 整体思路拆解搞清楚 React 项目部署到底要解决什么问题1.1 React 项目部署的本质不是“把代码跑起来”很多前端第一次接触部署时有个错觉部署 React 项目就是把它当 Node 服务跑起来。这是最常见的理解偏差。React 项目构建完了之后产物是一堆静态文件HTML、JS、CSS、图片、字体。这些文件不需要 Node 运行时去执行真正需要的是一个能高效托管静态文件、并能处理路由分发的服务。用 Node 起一个 express 或 koa 服务去托管静态文件当然也能跑但生产环境里 Nginx 是更普遍的选择原因很简单处理静态文件性能更好、内存占用低、配置灵活而且对前端路由尤其是 BrowserRouter 模式的支持非常成熟。所以这个实践的最终架构就是React 源码 → 构建产物 → Nginx 托管 → 容器分发。想明白这一层后面写 Dockerfile 时的各种选择就顺理成章了。1.2 为什么一定要用 Docker 而不是直接把文件丢到服务器直接 scp 把 build 目录传到服务器再让 Nginx 指过去也不是不行。但问题在于环境的一致性、迁移的便捷性、多台服务器分发时的重复劳动。你用 Docker 把整个运行环境包括 Nginx 版本、配置文件、静态资源打成镜像意味着在任何安装了 Docker 的机器上docker run就能得到一模一样的服务不存在“我本机跑得好好的到你服务器就 404”这类玄学。另外Docker 镜像本身是分层的。React 构建过程中的依赖安装、代码打包、运行时配置每一阶段都可以独立成层。利用好这些层次缓存迭代部署时构建速度会快非常多。这个优势在 CI/CD 流程里尤其明显一次构建多环境复用从开发到预发到生产都走同一个镜像最大程度减少环境差异导致的问题。1.3 整个部署流程的路径图整体路径大概是这样的本地开发完 React 项目 → 编写 Dockerfile 定义构建和运行阶段 → 构建镜像 → 本地用 docker run 验证 → 编写 docker-compose.yml 定义完整服务 → 推到服务器执行。其中核心是 Dockerfile 的多阶段构建以及 Nginx 配置对 SPA 路由的适配这两个环节是排障高发区后面重点展开。2. 环境准备Docker 安装与基础验证2.1 先装好 Docker无论你是什么系统如果我前面讲的概念你都理解了现在是动手环节。环境准备很关键至少要把 Docker 跑起来。装 Docker 没有统一的三步走系统不同方式不同但思路是一致的安装引擎 → 启动服务 → 验证可用。Windows 用户建议直接装 Docker Desktop它自带图形界面能直观看到镜像、容器、卷的状态对新手友好。但要注意新版本的 Docker Desktop 要求开启 Windows 的 Hyper-V 或 WSL 2装完如果报类似 “Virtualization support not detected” 的错十有八九是 BIOS 里虚拟化没开或者 WSL 2 没装好。这类问题很常见我遇到过不止一次排查思路稍后展开。Linux 服务器上装 Docker各发行版命令不同。Debian/Ubuntu 系的经典推荐是用官方脚本如果你对这个操作谨慎也可以先更新 apt 索引再装 docker.io 或 docker-ce但本质都是装一个 docker 引擎。装完最好让当前用户加入 docker 组否则每次都要 sudo 执行 docker 命令很痛苦而且 sudo docker 有权限风险也容易让后面的脚本权限混乱。macOS 同样用 Docker Desktop或者用 OrbStack 这类轻量替代品也行。无论哪种系统装完第一件事是把 docker 跑起来然后验证一下docker version docker run hello-world第二个命令会从官方仓库拉取一个 tiny 镜像并执行看到 “Hello from Docker!” 就说明整个链路通了。这一步别跳过很多后续问题都是因为 Docker 服务根本没起来而导致的。2.2 确认 Node 环境和项目结构这个项目示范默认你的 React 项目用的是标准结构即package.json在根目录有 build或 build:xxx脚本。实际项目里用的构建工具是 Vite 还是 CRA脚本名会有差异但 Dockerfile 思路是完全一致的只需替换成对应的包管理器命令即可。准备工作就绪后打开项目根目录看看有没有.dockerignore文件。没有的话一定要建一个内容和.gitignore类似把node_modules、dist、build、.git等目录排除掉。这个文件经常被忽略但它直接决定了构建上下文的体积。没有它Docker 会把整个项目目录包括动辄几百 MB 的 node_modules打包进构建上下文即使后续构建里用不到传输开销也是实打实的。3. 核心实现编写 Dockerfile 并完成镜像构建3.1 多阶段构建为什么是它以及每一阶段在干什么Dockerfile 里最核心的理念是多阶段构建multi-stage build。新手最容易犯的错误是试图用一个镜像同时完成“装依赖 构建 运行”结果就是镜像体积巨大动辄一两 GB而且把构建工具链暴露在生产环境里既不安全也没必要。多阶段构建的思路很直白第一阶段负责把源代码变成构建产物第二阶段只要产物和一个静态服务器。阶段之间通过COPY --from把需要的文件传递过来其他的一概不要。最终镜像里只有 Nginx 和静态文件干净利落。# 语法声明 # syntaxdocker/dockerfile:1 # 阶段一构建 FROM node:20-alpine AS builder WORKDIR /app # 单独复制 package 文件充分利用层缓存 COPY package.json package-lock.json* yarn.lock* pnpm-lock.yaml* ./ RUN npm install # 复制源码并构建 COPY . . RUN npm run build # 阶段二运行 FROM nginx:alpine # 从构建阶段复制产物到 Nginx 的默认站点目录 COPY --frombuilder /app/dist /usr/share/nginx/html # 复制我们自定义的 Nginx 配置 COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD [nginx, -g, daemon off;]npm install这一步我单独拎出来放在COPY package.json之后是有讲究的。Docker 的层缓存机制按指令逐层判断只要COPY的源文件内容没变化这一层结果就可以直接复用。也就是说你改了代码但没改依赖时docker build 会跳过依赖安装这一步直接命中缓存构建时间从几分钟降到几秒这是实际开发中非常实用的优化。这段示例里COPY package.json package-lock.json* yarn.lock* pnpm-lock.yaml*属于通配写法把几种主流包管理器的锁文件都列上了实际项目只需保留你正在用的那个。npm 就留 package.json 和 package-lock.jsonyarn 就留 yarn.lockpnpm 就留 pnpm-lock.yaml避免回溯干扰。3.2 Alpine 版本选择为什么推荐 Node 20-alpine 和 Nginx-alpine基础镜像选型有门道。node:20-alpine和nginx:alpine用的都是 Alpine Linux体积小、攻击面小、启动快。Alpine 本身是一个极简 Linux 发行版镜像只有几 MB 到几十 MB而标准的 node:20 镜像动辄几百 MB。对于前端部署这种只需要 Node 来构建、Nginx 来托管的场景Alpine 是更合适的选择而且部署到生产环境后基础组件的 CVE 更少维护成本更低。如果因为某些底层依赖比如原生模块必须在标准镜像里编那就别硬上 Alpine否则会碰到 musl libc 和 glibc 兼容性问题踩坑成本不划算。普通 React 项目基本不会遇到这个问题但如果你是 SSR 或用到了一些带原生绑定的库镜像选型时要先做验证不能一味追求小体积。还有一点容易被忽略Node 版本。老项目里 React 依赖的库可能比较旧直接上 node:20-alpine 可能因为OpenSSL版本问题编译报错当时比较常见的错误是digital envelope routines::unsupported这其实是 Node 17 之后默认启用了 OpenSSL 3而旧构建工具不兼容导致的。这种情况下用 node:16-alpine 或者指定兼容版本比纠结各种 workaround 来得更靠谱。所以如果你的项目是陈年老项目建议先用node:16-alpine或node:18-alpine试本章节给出的参数可基于常见实践调整具体使用时按你的项目构建环境来定版本。3.3 从零开始构建镜像的完整过程记录项目结构先准备好这里我以一个假设的、相对标准的 React 项目为例Dockerfile、nginx.conf、.dockerignore 均置于项目根目录。.dockerignore至少要长这样node_modules dist build .git .DS_Store docker-compose*.yml Dockerfile有朋友可能会问Dockerfile 自己都在项目里怎么还要 ignore原因很简单每次构建时 Docker 会把整个项目目录作为上下文传给 daemon只要项目目录里的内容变化了就等于上下文变化了构建缓存就可能失效。Dockerfile 本身不参与构建所以把它排除掉没任何影响还能减小上下文。然后执行构建docker build -t my-react-app:latest .这里的.就是构建上下文路径指向当前目录。-t给镜像打 tag命名规则一般是项目名:版本号实际部署时可以用后端服务名.项目名的格式组织方便 registry 管理。第一次构建会拉取基础镜像并安装依赖耗时取决于网络状况一般在几分钟到十分钟不等。第二次构建时只要你的依赖文件没变命中缓存后速度会有质的提升。构建完成后用docker images查看镜像列表按我们的设计最终镜像体积应该在几十 MB 级别。如果镜像出现 1GB 的情况说明多阶段构建没起作用仔细看 Dockerfile多半是最后 COPY 了不该 COPY 的东西或者基础镜像选错了。4. Nginx 配置与 SPA 路由适配容易出坑但必须处理好的环节4.1 为什么 BrowserRouter 会出现 404以及 Nginx 如何兜底React 项目用了 BrowserRouter 时前端路由是路径式的比如/about或/user/123。用户在首页点击跳转时没问题因为这是前端 history API 在起作用但如果你直接访问/about请求会到达 Nginx而 Nginx 默认去/usr/share/nginx/html/about找文件这个文件当然不存在就返回 404。这就是最常见的“部署之后刷新页面就白屏/404”问题。解决办法是配置 try_files把所有不存在的路径都指向index.html让前端路由接管server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } }这里try_files的语法是依次尝试去找$uri请求的原始路径、$uri/目录形式都找不到就回退到/index.html。配合前端的 BrowserRouter页面加载完后 JS 会读取当前路径并渲染对应组件路由就不会失联了。4.2 静态资源缓存策略让长期不变的文件走强缓存前端构建产物里带 hash 的文件名比如index-a1b2c3.js意味着内容变了文件名也会变这类文件适合设置较长的强缓存浏览器直接本地取用不再发请求。不带 hash 的如index.html则应该设置no-cache确保每次访问都能拿到最新版本不至于部署后用户还在用旧页面。location /assets/ { expires 30d; add_header Cache-Control public, immutable; } location / { try_files $uri $uri/ /index.html; add_header Cache-Control no-cache; }这种配置方案是为了让不同资源各归其位不可变资源带 hash 的静态文件用长缓存可变入口HTML要实时校验。对于需要立即回源更新的场景还可以配合 Nginx 的Cache-Control: no-store不过一般前端部署场景还不会走这一步此处略过。4.3 反代与 gzip生产环境配置里顺手就做的事如果你的前端需要请求后端接口而前后端是分开部署的那 Nginx 还承担了反向代理的职责。把所有/api开头的请求转发到后端服务完美绕开跨域问题。这块配置虽然不属于“部署 React 项目”的必要项但实际项目里几乎一定会遇到建议直接写进 nginx.conflocation /api/ { proxy_pass http://backend:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; }这里backend是在 docker-compose 里定义的服务名Docker 内置 DNS 会自动解析不需要写死 IP。顺带把 gzip 开起来虽然 2025 年了还有朋友纠结要不要开这和性能优化相关预算足够的实战里顺手就做了。静态资源本身经过构建工具压缩过一次但 Nginx 这层的 gzip 对 HTML、JSON 等动态/半动态内容的收益更明显。还有 brotli如果你的 Nginx 镜像里包含了 brotli 模块也可以开启压缩率比 gzip 更高但兼容性取决于实际环境。5. docker-compose 编排与一键部署从单容器到完整服务5.1 为什么需要 docker-compose而不直接用 docker run前端项目不可能永远是孤零零一个容器。你有后端服务有数据库可能还要 Redis。如果全部靠docker run一条条手动执行参数多、容易漏、可复现性差。docker-compose 就是把多个容器定义成一个整体服务栈一条命令全启动一条命令全停配置代码化环境变量集中管理。实际上 compose 本身就是一个用 YAML 定义容器的 DSL它声明了镜像、端口、环境变量、依赖关系、卷等。部署 React 前端时就算暂时没有后端先学会用 compose 管理前端容器也是值得的因为后续扩展几乎必然走到这条路上。一个最小的 docker-compose.yml 长这样services: web: build: . image: my-react-app:latest ports: - 3000:80 restart: unless-stopped这里的build: .表示当前目录下找 Dockerfile 构建image给生成的镜像命名。ports把宿主机的 3000 端口映射到容器的 80 端口。此时访问你的服务器 IP:3000 就能看到页面。5.2 前后端联调的 compose 配置实例实际项目里 compose 文件长这样才更接近真实场景services: frontend: build: . ports: - 80:80 depends_on: - backend restart: unless-stopped backend: build: ../backend ports: - 8080:8080 environment: DB_HOST: db DB_PORT: 3306 depends_on: - db restart: unless-stopped db: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: your_password MYSQL_DATABASE: your_db volumes: - db_data:/var/lib/mysql ports: - 3306:3306 restart: unless-stopped volumes: db_data:这也是我建议前端同学积极拥抱 Docker 的一个重要原因本地开发时不用再费劲装 MySQL、Redis 这些服务compose 起来一套用完了docker compose down收拾干净省心太多。注意这里的db我暴露了3306:3306方便本地用 Navicat 或命令行工具连接调试。生产环境数据库端口一般不必暴露给宿主因为内网服务之间通过 Docker 网络就能互访。这个“暴露 vs 不暴露”的决策是新手最容易踩的安全坑最好是根据实际场景权衡。5.3 启动与更新服务的标准操作docker compose build docker compose up -d第一条命令构建镜像第二条命令后台启动所有服务。-d表示 detached即后台运行。加了restart: unless-stopped之后容器挂了会自动重启服务器重启也会跟着起来一般生产环境都会加。更新部署时git pull docker compose build frontend docker compose up -d frontend这里up -d frontend后compose 会对比现有容器和新定义的差异发现有新镜像后就自动重建不需要手动 stop/rm。如果你要彻底重启某个服务用docker compose restart frontend要查看日志用docker compose logs -f frontend。这些命令多用几次就熟了比操作多个 docker run 容器的记忆成本低得多。6. 常见问题与排查技巧实录那些实际部署中反复出现的坑6.1 Docker Desktop 在 Windows 上启动失败报错信息五花八门最常见的是virtualization support not detected或者服务启动后一直卡在 starting 状态。排查顺序是先确认 BIOS 里的 virtualization 功能Intel VT-x 或 AMD-V开启。Windows 上查看是否有 Hyper-V 或 WSL 2 启用可以用命令或直接在控制面板里看。Docker Desktop 新版默认走 WSL 2 后端如果 WSL 2 的虚拟机没装好Docker 就起不来。最直接的验证是在 Windows Terminal 里敲wsl --status查看默认版本。如果显示版本 1 或没有已安装的发行版就需要更新 WSL 内核并安装一个发行版。补充一个常见现象本地开了 Android 模拟器或其他虚拟化软件占了虚拟化资源Docker 也可能启动失败。这时把模拟器关掉再启动 Docker 试试十有八九能解决。6.2 构建时提示权限不足、上下文过大或网络超时Docker 构建是在 Docker daemon 里执行的而 daemon 又是一个 root 进程。这意味着项目里的任意文件构建阶段都能访问。所以第一个排查点是文件权限——如果你以前手上加过 ACL 之类的限制构建上下文里有敏感文件时除了用 .dockerignore 做排除还建议用--secret这类构建特性传递敏感信息别直接把密钥 COPY 进镜像。构建上下文过大往往是 node_modules 没排除。在项目根目录运行docker build前先检查目录大小几千个文件会让构建上下文打包过程非常慢。网络超时基本是国内拉取镜像和 npm 依赖慢导致这类问题可以把 Docker daemon 或 NPM registry 镜像配成国内镜像源配置方式网上很多此处不复述但实际操作中确实有效。6.3 容器起来了但页面白屏或 404排查顺序很重要先确认容器运行状态docker ps看看再确认端口映射docker port container_id都没问题就进容器看内容docker exec -it container_id sh在容器里 ls 一下/usr/share/nginx/html看文件是否真的存在。有的项目构建输出目录不是dist而是build或outCOPY 路径写错就会得到一个空目录自然白屏。确认文件在但 404就是 Nginx 配置问题重点看 try_files 有没有配对。确认页面能打开但刷新后 404基本只有 BrowserRouter try_files 这一个原因。把 nginx.conf 改正确重新构建部署问题就没了。6.4 镜像更新后页面没变化以及如何干净清理部署新版本后浏览器还在用旧缓存往往是 index.html 也走了强缓存。解决方式就是在配置里给 HTML 设置 no-cache给带 hash 的资源设置长期缓存。如果真的想看当前容器运行的是什么镜像、什么时间构建的可以用docker inspect container_id里面能看到镜像 ID 和创建时间方便核对版本对应关系。docker system df可以查看磁盘占用情况docker system prune -a能清理没有使用的镜像、容器、网络。这条命令要慎用如果清楚自己的目标再执行否则可能把想要保留的中间层镜像也删了重建时虽然不影响最终正确性但会损失缓存提速。6.5 ARM 架构部署rk3588、Jetson 这类设备上跑 Docker 的差异如果要把项目部署到 AI 边缘盒子、RK3588 开发板、Jetson Orin 这类 ARM 设备上流程不变但有两个细节要注意。第一镜像必须拉 arm64 版本。官方镜像如 node、nginx直接就有 multi-arch manifestDocker 会自动选不用手动干预。但如果项目依赖的某个镜像只有 amd64 版在 ARM 上跑会直接报 exec format error。第二如果基础镜像需要自己构建例如将 YOLOv8 或模型推理服务打进镜像建议在设备上直接构建交叉编译容易踩底层依赖的坑。还有一点资源受限的嵌入式设备上内存往往不大npm install和npm run build可能因内存不足被杀这时可以先在本地或 CI 里构建好再把镜像导出后拷到设备上去加载用docker save和docker load最稳。7. 部署后的常用操作与真实体验分享部署完成只是开始日常维护其实是围绕几条命令转的看日志、看资源、进出容器。看日志是docker logs -f 容器名或ID调试时非常有用前端项目尤其要看 Nginx 的 error log很多白屏问题都会在这里留下线索。看资源占用用docker stats实时显示容器 CPU 和内存。要修改容器里面的配置先用docker exec -it 容器名 /bin/sh进去改了以后最好重新构建镜像直接在容器里改属于应急手段重启就没了。我自己的习惯是每次交付代码都在本地把整个流程完整跑一遍包括构建、运行、验证页面确认无误再 push。上了服务器之后先在服务器上构建或拉取镜像然后起一个新容器验证没问题再切换流量减少停机时间。这里的执行路径还需要注意灰度发布的逻辑否则会出现新代码上线后回滚困难的问题实际项目中通常是在 CI/CD 里做版本控制的优化。还有一个非常实用的建议尽量把docker compose build这一步放到 CI 里去例如 GitLab CI、GitHub Actions 都行甚至本地有 Jenkins 也可以。本地构建镜像然后推到服务器不仅慢且容易把本机的脏环境带进去CI 里构建的镜像更干净而且带自动版本号回滚也更方便——镜像 tag 跟 git commit 编号关联这个习惯真的能救命。我见过太多人镜像 tag 永远是 latest出了事故想回滚都不知道回滚到哪一版。最后分享一个我之前踩过的真实坑公司那台老服务器上 Docker 版本特别旧不支持某些新语法特性比如 Dockerfile 里的COPY --chown或较新的构建缓存 API结果 CI 里构建好好的镜像到服务器死活起不来。排查半天最终把服务器上的 Docker 升级到新版本一切恢复正常。所以如果你在部署时遇到诡异问题先把 Docker 版本、Nginx 版本、Node 版本列一遍环境版本差异往往是第一根源。