企业官网建设流程全解析

前端项目部署这件事，说难不难，说简单也真没那么简单。你本地跑得好好的 React Vite 项目，传到服务器上可能就是另一副面孔：Node 版本不对、npm install 装到一半崩了、跑起来首页倒是能开，一刷新子路由就 404。这些问题的根源只有一个——环境不一致。

Docker 解决的就是这个问题，它把你的应用连同运行环境一起打包成一个标准镜像，到哪台机器上都是同一个跑法，不再有“在我电脑上能跑”这种说法。这篇文章从零开始，不预设你已经用过 Docker，只要你会基础的 React 开发和 Linux 命令，就能跟着一步步把项目容器化，走完从安装 Docker、写 Dockerfile、构建镜像、启动容器到配置 Nginx 的完整链路。

下面我会把每一步的“为什么”也讲清楚，不只是给你一段能用的配置，而是让你理解这套方案背后的取舍。文章最后整理了我在实际部署中踩过的坑和排查思路，看完能帮你省下至少一个下午的 debug 时间。

1. 把前端项目装进 Docker，到底解决了什么问题

1.1 从一次“在我电脑上能跑”说起

几年前我在团队里接手一个已经迭代了两年的后台管理系统，代码从前端到部署脚本全是前任留下的。本地跑没问题，但每次发布上线都要经历一轮折腾：先确认服务器上的 Node 版本，再跑 npm install，运气不好还要处理 Python 环境的 node-sass 编译问题，整套下来小半天就没了。

后来我养成了一个习惯——项目交接也好、团队协作也好，第一件事就是把运行环境固定下来。Docker 不是银弹，但它确实是目前处理“环境一致性”最成熟的方案：镜像把代码、运行时、依赖、配置文件全部固化，任何一台装有 Docker 的机器都能还原出完全相同的运行环境。

对前端项目来说，容器化带来的收益主要集中在三个方面：

• 构建环境可复现：开发用 Node 18，生产也用 Node 18，依赖锁定版本，CI 里构建的产物和本地构建的产物理论上完全一致。
• 部署过程标准化：服务器上不再需要手动安装 Node、Nginx，只需要docker run一个命令就能把服务拉起来。
• 回滚变成切镜像：旧版本镜像还在，出问题直接切回去，不用重新拉代码重新构建。

1.2 方案选型：为什么是 nginx + 多阶段构建

前端容器化有一个经典的组合：Node 镜像负责构建，Nginx 镜像负责运行，中间用多阶段构建把两者串联起来。这套方案能成为主流不是偶然。

先看 Nginx。前端构建产物是纯静态文件，理论上任何静态文件服务器都能跑，Python 的http.server都能胜任。但生产环境要考虑的远不止“能访问”：SPA 路由回退要配、静态资源缓存要配、Gzip 压缩要配、HTTPS 证书要挂。Nginx 在这些方面有几十年的积累，配置文件写清楚之后非常稳定可靠，这是 Node 写的serve这类轻量方案比不了的。

再看多阶段构建。如果你只写一个FROM node:18，然后把整个 node_modules 打进镜像再跑npm run start，镜像会有多大？Node 18 完整镜像大概 1GB 左右，还不算 node_modules 的体积。而多阶段构建的思路是：第一阶段用 Node 镜像构建出静态资源，第二阶段把静态资源拷贝进一个干净的 Nginx 镜像里。最终镜像里只有 Nginx 和 dist 文件夹，体积一下压缩到几十 MB，攻击面也更小——生产容器里根本没有 Node 进程可打。

提示：多阶段构建不是前端专用技巧，任何“需要编译期依赖但不希望带到运行期”的场景都适用。比如 Go 项目用 golang 镜像交叉编译，再用 scratch 镜像运行，同一个思路。

1.3 场景拆分：开发环境和生产部署要分开对待

刚开始学 Docker 的人很容易犯一个错误：想用 Docker 把本地开发也包进去。我试过在 Docker 里跑 Vite dev server，体验非常割裂——热更新慢、断点调试不好使、文件监听偶尔失灵。

我的建议是明确区分两条链路：

• 本地开发：继续用本机的 Node +npm run dev。Vite 的热更新和浏览器调试体验是容器暂时给不了的。
• 生产部署：用 Docker 走构建 + Nginx 静态托管的方案。

具体的做法是，本地开发完全不用 Docker，代码推到仓库后，由 CI 或手动执行 Docker 构建，构建出的镜像拿到服务器上跑。这样兼顾了开发体验和生产一致性，也是目前前端 Docker 化的标准姿势。

2. 环境准备与镜像的核心构件

2.1 Docker Desktop 安装与那两个 Windows 专属坑

Docker 本身是 Linux 上的技术，Windows 和 macOS 想用就得靠一层虚拟机。macOS 上 Docker Desktop 基本是双击安装、一气呵成，而 Windows 上就麻烦一些，最常见的就是启动时报Virtualization support not detected。

这个报错的含义是 Docker Desktop 依赖的虚拟化功能没开启，通常有三个原因：

1. BIOS 里的 CPU 虚拟化被关掉了。重启进 BIOS，找 Intel VT-x 或 AMD-V 的开关，设置成 Enabled。
2. Windows 功能里没启用 WSL2 或 Hyper-V。在“启用或关闭 Windows 功能”里勾选“适用于 Linux 的 Windows 子系统”，如果是老版本系统还得手动开 Hyper-V。
3. Docker Desktop 设置的 backend 不对。新版多数默认用 WSL2 backend，如果之前装过旧版 Docker Toolbox，可能还残留着 Hyper-V backend 的冲突。

装好之后验证一下环境和版本：

docker --version docker compose version docker info

docker info能输出大量运行时信息，如果正常显示Server Version就说明 Docker 引擎已经跑起来了。

2.2 Dockerfile 逐行拆解：多阶段构建到底多写了什么

写 Dockerfile 是整套流程的核心环节，我直接给一份生产可用版本，再逐行解释：

# 第一阶段：构建前端静态资源 FROM node:18-alpine AS build WORKDIR /app COPY package.json package-lock.json ./ RUN npm ci --registry=https://registry.npmmirror.com COPY . . ARG VITE_APP_API_URL ENV VITE_APP_API_URL=$VITE_APP_API_URL RUN npm run build # 第二阶段：Nginx 托管静态资源 FROM nginx:1.25-alpine COPY --from=build /app/dist /usr/share/nginx/html COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]

逐行来看几个关键点：

• FROM node:18-alpine AS build：以 18 版本为基础镜像，-alpine是精简版，体积更小。给它起了个名字叫build，后续阶段可以引用。
• COPY package.json package-lock.json ./：先把依赖清单拷进容器。这里单独一步是有讲究的——Docker 构建有缓存机制，只要这一层涉及的文件没变，后续步骤就能直接复用缓存。如果先把全部代码拷进去再执行npm install，那么每次代码变动都会导致依赖重新安装一遍，构建慢到怀疑人生。
• RUN npm ci：npm ci会严格按 lock 文件安装依赖，不会像npm install那样自作主张升级版本。配合package-lock.json，能保证构建环境依赖完全一致。
• RUN npm run build：执行 Vite 构建，生成 dist 目录。
• FROM nginx:1.25-alpine：第二阶段从 Nginx 镜像开始，--from=build表示从第一阶段构建的临时镜像里拷贝文件。到这里，Node 和 node_modules 全被丢掉，最终镜像里只有 Nginx 和编译好的静态文件。

npm ci这里有个细节：它要求package.json和package-lock.json必须同步，否则会直接报错。这其实是好事，逼着你提交 lock 文件、保证依赖可复现。

2.3 别忘了 .dockerignore 和 npm 镜像源

很多新手写 Dockerfile 只关注内容，忘了.dockerignore文件，结果构建时把本地的 node_modules 也打进构建上下文了。前面COPY . .这行的意思是把当前目录所有文件都拷进容器，如果没有忽略规则，那速度慢不说，还可能出现 Windows 下的原生依赖被拷进 Linux 容器导致构建失败。

.dockerignore和.gitignore的作用类似，至少要包含这些：

node_modules dist .git .gitignore .editorconfig Dockerfile .dockerignore .env .env.local *.log .DS_Store

至于 npm 镜像源，国内网络环境下一句npm ci可能就是几分钟的等待。我习惯在 Dockerfile 里直接用--registry参数指定镜像源，这样不依赖宿主机 npm config。如果你的用户不在乎这点网络差异，去掉也完全可以。

2.4 nginx.conf：SPA 路由不回退 404 的关键

React 项目默认是单页应用，前端路由由 JS 控制，浏览器拿到的是整个应用框架再按路径渲染组件。问题在于：用户直接访问www.example.com/user/123时，浏览器会先向服务器发起对/user/123这个路径的 HTTP 请求，服务器上根本没有这个文件，Nginx 默认会返回 404。

所以 Nginx 配置必须做一件事——所有路径都回退到index.html：

server { listen 80; server_name _; root /usr/share/nginx/html; index index.html; # Gzip 压缩，减少传输体积 gzip on; gzip_types text/plain text/css application/javascript application/json image/svg+xml; gzip_min_length 1024; # 所有请求回退到 index.html location / { try_files $uri $uri/ /index.html; } # 静态资源带指纹，强缓存 7 天 location /assets/ { expires 7d; add_header Cache-Control "public, no-transform"; } }

try_files $uri $uri/ /index.html是 SPA 部署的灵魂：先找对应文件，再找对应目录，都找不到就返回 index.html，把路由交给前端处理。/assets/单独配置是因为 Vite 构建产物里的 JS、CSS 都带哈希指纹——文件名变了旧缓存自动失效，没有指纹的入口文件index.html反而不能强缓存，否则更新后用户还在看旧页面。

3. 从零开始完整实操：构建、运行、编排

3.1 第一步：初始化一个 Vite React 项目

先创建一个测试项目来走完整流程。Vite 是现在首选的 React 脚手架，比 CRA 快得多，配置文件也清晰：

npm create vite@latest react-docker-demo -- --template react cd react-docker-demo npm install

项目结构里最核心的几个文件：

• src/：React 源码
• vite.config.js：构建配置
• package.json：依赖和脚本
• index.html：入口页面

先本地跑一遍确认项目本身没问题：

npm run dev

浏览器打开http://localhost:5173，能看到 Vite 默认的 React 欢迎页就说明项目初始化成功。

3.2 第二步：构建前端产物并本地验证

在写 Docker 之前，先用 Vite 原生的构建命令验证产物正常：

npm run build

构建完成后会在项目根目录生成dist/文件夹，里面是压缩优化过的静态资源。你可以参考 Searx 这篇文章里的方法，在本地静态跑一下验证效果。

这里要注意一个细节：Vite 默认的base是根路径/，如果你的前端部署在域名根路径下，什么都不用改。如果要部署到类似http://example.com/admin/的子路径，需要在vite.config.js里设base: '/admin/'，同时 Nginx 的 location 也要对应调整。这个坑很容易被忽略，等你部署完发现图片全挂了、路由全 404 才反应过来。

3.3 第三步：编写 Dockerfile 和 Nginx 配置

在项目根目录创建Dockerfile，内容就用我上面给的那份。然后再创建nginx.conf，内容也用上面那份。如果你需要配置后端 API 转发，比如把/api开头的请求反代到后端服务，需要在 nginx.conf 里加上：

location /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; proxy_set_header X-Forwarded-Proto $scheme; }

这个配置等于把容器内的/api请求转发到backend主机的 8080 端口。这里的backend是 docker-compose 里的服务名，在 Docker 内网环境里能直接解析。

3.4 第四步：构建镜像与启动容器

项目根目录执行构建：

docker build -t react-docker-demo:1.0 .

-t给镜像打标签，格式是名称:标签，1.0 这样自己管理版本号即可。首次构建会花几分钟下载基础镜像，之后构建就快多了。

构建完成后查看镜像列表：

docker images

你会在列表里看到 Nginx 镜像和最终构建产物镜像，最终镜像体积应该在 50MB 左右，如果超过 200MB，大概率是中间阶段的临时层被误打进了镜像。

启动容器：

docker run -d -p 8080:80 --name react-demo-container react-docker-demo:1.0

参数拆解：

• -d：后台运行
• -p 8080:80：把容器的 80 端口映射到宿主的 8080 端口，浏览器访问http://localhost:8080就能看到页面
• --name：给容器命名，方便后续管理

运行后查看日志确认 Nginx 启动成功：

docker logs react-demo-container

再进入容器里检查文件是否正确拷贝：

docker exec -it react-demo-container sh ls /usr/share/nginx/html

能看到index.html和assets/目录就说明构建阶段和拷贝阶段都正常。

3.5 第五步：用 docker-compose 把前后端塞进一套编排

真实项目里前端通常不是单独部署的，后面多半还跟着一个后端接口服务。与其一个个docker run，不如用 docker-compose 把服务编排在一起。在项目根目录创建docker-compose.yml：

version: "3.8" services: frontend: build: . ports: - "8080:80" depends_on: - backend backend: image: node:18-alpine working_dir: /app volumes: - ./backend:/app command: sh -c "npm install && npm run server" environment: - PORT=8080

然后在backend/目录里放一个简单的 Node HTTP 服务。启动整个编排：

docker compose up -d

depends_on保证后端先启动再启动前端，但要注意这个指令只决定启动顺序，不负责健康检查。生产环境建议给后端加healthcheck，等健康检查通过后才把流量切过去。

用 compose 管理还有一个好处：docker compose down一键停掉所有服务，环境清理非常干净。

3.6 进阶：运行时注入环境变量的正确姿势

所有前端项目都会遇到这个问题：开发环境的 API 地址和生产的地址不一样，但你又不想分别构建两套镜像。很多人的做法是构建时用--build-arg传参数，这确实可行，但有个弊端——环境变了就得重新构建镜像。

更优雅的做法是把环境变量注入推迟到容器启动时。Nginx 本身有envsubst能力，可以在容器启动时用环境变量替换模板占位符。

思路是这样的：把 nginx.conf 写成一个模板文件，变量用$占位，然后写一个 entrypoint 脚本在启动前做替换。

也可以利用 Nginx 官方的镜像特性，它自带/docker-entrypoint.d/机制，支持模板文件替换。如果你不想搞得太复杂，构建时用ARG + ENV传参是最快路径，但记住：镜像一旦构建，环境变量就焊死在里面了。换环境就要重新构建，更适合 CI/CD 流程中分环境构建的场景。

4. 高频踩坑记录与排查思路

4.1 启动 Docker Desktop 直接报 Virtualization support not detected

这是我们开头提到的问题。完整报错一般是：

Docker Desktop - Virtualization support not detected

排查步骤按顺序来：

1. 重启进 BIOS，确认 Intel VT-x 或 AMD-V 是 Enabled。
2. Windows 搜索“启用或关闭 Windows 功能”，勾选“适用于 Linux 的 Windows 子系统”，老系统还要勾选“Hyper-V”，重启。
3. 打开 PowerShell 执行wsl --status确认 WSL2 正常。
4. 最后再启动 Docker Desktop。

这个问题是 Windows 上装 Docker 的第一大拦路虎，根因基本都是系统虚拟化相关组件没配齐。

4.2 容器起来了但网页打不开或网络不通

docker run成功，端口也映射了，但访问localhost:8080就是打不开。先确认端口映射是否生效：

docker ps

看PORTS列，如果显示0.0.0.0:8080->80/tcp说明映射正常。如果显示的是127.0.0.1:8080->80/tcp，那说明只监听了本机回环地址，外部访问不到。

容器内部网络不通是另一个常见问题。先进入容器测试网络：

docker exec -it react-demo-container sh ping 8.8.8.8

如果 ping 不通，多半是宿主机 DNS 配置问题。在/etc/docker/daemon.json里添加：

{ "dns": ["8.8.8.8", "114.114.114.114"] }

重启 Docker 服务后生效。容器网络配置这块，跟 Zabbix 这类系统监控工具部署时遇到的网络问题排查思路很类似——先通宿主机，再通容器内，逐层定位。

4.3 端口占用：8080 端口已经被系统服务占了

在 Windows 上还会遇到一种特殊情况：8080 端口明明没装什么软件，但就是被占用。系统更新后 Hyper-V 会保留一批端口范围，导致你无法监听。

排查思路：

netstat -ano | findstr :8080

如果看到 PID 叫System且 PID 是 4，大概率就是 Hyper-V 的端口保留。可以用netsh interface ipv4 show excludedportrange protocol=tcp查看保留端口范围。

最简单的处理办法是换一个映射端口，比如-p 8081:80。一定要用 8080 的话，可以用netsh int ipv4 set dynamicport tcp start=10000 num=20000把这段端口排除出保留范围再重启系统，不过没必要为了一个端口这么折腾，换端口最省事。

4.4 刷新页面就 404：SPA 路由的回退问题

这是几乎所有前端 Docker 化的人都会遇到的经典问题：访问首页没问题，点击跳转也没问题，一按 F5 就 404。

原因在上面讲 nginx.conf 时说过了——浏览器直接向服务器请求/user/123这个路径，服务器没找到文件就返回 404。没有加try_files的 Nginx 配置就是这个结果。

确认你的 nginx.conf 里是否有这样一行：

location / { try_files $uri $uri/ /index.html; }

加上之后重新构建镜像、重启容器就解决了。这个坑太常见了，导致我第一次遇到的时候完全不慌，心里清楚就是配置缺失的问题。

4.5 镜像体积失控与构建速度慢

构建出来的镜像体积大，通常有三个原因：

1. 没有用多阶段构建，把整个 node_modules 塞进了最终镜像。
2. 基础镜像 tag 用错，用了完整的node:18而不是node:18-alpine。
3. 缺少 .dockerignore，本地 node_modules 被拷进构建上下文又被打进镜像。

构建速度慢则多半是缓存没命中。Dockerfile 里COPY package.json package-lock.json ./单独一步的目的就是利用 Docker 层缓存——只要这两份文件没变，之后到RUN npm ci都不会重复执行。

但有一个容易忽略的细节：Docker 的层缓存非常“敏感”，上面任何一层文件变了，后面所有缓存都会失效。所以 Dockerfile 里应该把“变化频繁的代码复制”放到最靠后的位置，把“变化不频繁的依赖清单”放在最前面。COPY . .这一行不要写在npm ci前面，否则缓存就形同虚设了。

这套流程我在实际项目里跑了很多遍，从最开始手忙脚乱地在服务器上手动装 Node、装 Nginx、传代码，到后来变成一条docker build+docker run搞定，整个发布过程压缩到了几分钟。踩过的坑里，印象最深的还是那一次线上发布后用户反馈刷新页面就白屏，当时第一反应是代码有问题，折腾了半天才发现是 Nginx 没有配try_files。技术方案本身不复杂，复杂的是环境之间的隐性差异。

最后再分享一个小技巧：生产环境一定要用固定版本号的镜像标签，比如react-demo:1.0.0，不要用latest。不然哪天执行docker pull拉了一个意外的新版镜像，线上发布没经过验证就变了，到时候谁也说不清线上跑的是什么代码。镜像标签就是线上环境的版本记录，跟 Git tag 一样值得认真对待。