企业官网建设流程全解析

做前端这些年，Docker 本地部署 CSR 前端项目这个需求我碰上过不下二十次。每次不是帮同事救火，就是自己换了电脑之后重新搭环境。今天这篇就把整套流程完整拆开，从镜像怎么写、容器怎么跑，到路由回退、运行时变量、缓存策略这些躲不掉的坑，一次说清楚。无论你用的是是 Vue 还是 React，只要是纯前端项目（CSR 模式），这篇文章的每一段你都能直接照着操作。

文章基于我实际踩坑验证过的方案，也补充了本地部署最常见的权限、镜像、端口故障的排查链路。适合刚接触 Docker 的前端工程师，也适合需要把开发环境交付给团队统一使用的同学。我不打算写成 Docker 命令手册，而是尽量讲明白每一个选择的为什么，这样你以后遇到类似问题，即便没有这篇文章也能自己推导出答案。

1. 为什么纯前端项目也要塞进 Docker：本地部署的真实动机

1.1 前端依赖、环境与“跑不起来”的撕裂感

CSR 前端项目看起来复杂度不高，无非就是拉代码、装依赖、起 dev server。但现实里，组里五个人五个 Node 版本，跑同一个老项目，有人报gyp ERR，有人报node-sass编译失败，还有人npm install装到一半就报错。你要在本地部署一个像人力资源后台管理这类 Vue 项目，理论上要装 Node、npm、可能还要配 Java 后端、MySQL、Redis，整套环境手工搭下来，半天就没了。

Docker 解决的不是“能不能跑”，而是“为什么在你电脑上能跑、在我电脑上跑不了”这个工程化撕裂感。把构建环境和运行环境一起打包进镜像，开发、测试、生产看到的是同一种姿态。我第一次把 CSR 项目容器化之后，最大的感受不是部署变快了，而是“环境”这个东西终于从个人电脑里解耦了。换电脑、新同事入职、去客户现场临时演示，只需要一句docker run就能把项目拉起来，前提是先装好 Docker。

1.2 交付对象不是人，而是环境

很多人对 Docker 的第一印象是“虚拟机的轻量替代品”，这个类比方向对了一半。虚拟机虚拟的是整台操作系统，而 Docker 虚拟的是进程的运行环境。一个 CSR 前端项目本地部署，最终交付物其实不是代码，而是“运行代码所需的完整环境”：Node 构建环境、Nginx 托管环境、端口、可访问的 URL。

举个实际例子：早年间我在本地演示项目，最怕的就是现场没有外网，npm install直接卡死。而容器化以后，镜像本身已经把 node_modules 里该装的依赖都装好了，跑起来的是一个完整自洽的运行态。这种交付思路，才是本地部署“完整指南”的底层逻辑。理解了这一点，后面所有 Dockerfile 和配置的选择就有了方向。

提示：如果你的项目只在本地npm run dev跑过，还没用过生产构建产物，建议先确认npm run build能正常输出dist目录。容器化的一切基础，都建立在构建产物可用的前提下。

2. CSR 的本质是静态文件托管：先搞清楚 Nginx 在替你干什么

2.1 SSR、CSR、静态站点，部署姿态完全不同

CSR，即客户端渲染，Vue、React 的默认 SPA 模式都是 CSR。浏览器拿到的是一份空壳 HTML、JS、CSS，所有页面内容靠 JS 在浏览器里渲染出来。这与 SSR 完全不同，SSR 需要 Node 服务持续运行，每次请求都在服务端渲染 HTML；这决定了 CSV 项目的部署姿态，和静态站点生成器产出的纯静态文件几乎一致。

所以，部署一个 CSR 前端项目的核心动作是：构建静态文件，把这些文件交给一个 Web 服务器托管。Nginx 是干这件事最成熟、最通用的选择。你要知道自己打包出来的dist目录里是index.html、assets/js/xxx.hash.js这类文件，Nginx 的作用就是根据 URL 找到对应文件，用 HTTP 协议返回给浏览器。

2.2 Nginx 托管静态文件的最小逻辑

Nginx 处理静态文件只需要两个关键配置：root指定文件根目录，index指定默认首页。当用户访问/时，Nginx 会去root目录下找index.html；访问/assets/js/app.js时，去对应路径下找这个文件。

但这个默认逻辑在 SPA 项目里有一个致命问题：当用户直接访问/user/list时，服务器上并没有user/list.html这个文件，Nginx 会返回 404。而 CSR 项目的路由是前端用history模式自己维护的，正确的做法是：后端不管什么路径，都返回同一个index.html，由前端路由去解析。这个行为就是try_files参数解决的。

2.3 开发模式与生产模式的差异

本地开发时，Vue/React 的 dev server 内置了路由回退、热更新、代理，你根本感知不到这些底层问题。但容器化部署跑的是生产模式，没有 dev server 帮忙，所有路由、静态资源、代理规则都要自己在 Nginx 配置里显式写出来。我在第一次容器化时，“本地开发一切正常、docker 跑起来刷新就 404”就是这一章节认知不足导致的。

这就是为什么我要把这一章放在实操前面：不先搞懂 Nginx 在替你干什么，后面 Dockerfile 写得再漂亮，跑起来也是错的。CSR 项目部署从来不是“文件放进去就行”，而是“文件放进去之后，谁能被访问、以什么方式被访问”的问题。

3. 多阶段构建实战：从 Vue 源码到 Nginx 镜像的一行命令

3.1 选基础镜像：构建与运行要分开

一个 CSR 前端项目的完整镜像链路，一定绕不开两个阶段：构建阶段要 Node，运行阶段其实只需要 Nginx。很多人图省事，用一个node镜像装完环境、跑完构建，再硬装一个 Nginx，镜像体积能到 1GB 以上。正确做法是使用多阶段构建，用第一阶段的产物生成第二阶段，也就是最终交付的镜像。

基础镜像怎么选？我给一个适合大多数项目的组合：

我实际遇到过一个老项目，node-sass在 Alpine 镜像里编译不过，折腾半天，最后换成node:18-slim就好了。如果你的项目依赖里有原生模块，第一反应不要盲目追求 Alpine，先验证构建能否通过。这类兼容性问题，属于“本地部署没踩过不算完整”的典型代表。

3.2 Dockerfile 完整写法与每一行的来由

下面这份 Dockerfile 是 Vue 项目的标准写法，我逐行拆解一下它为什么这么写。

# 阶段一：构建 FROM node:20-alpine AS build WORKDIR /app # 先拷贝依赖清单，再安装依赖，是为了利用 Docker 的层缓存 COPY package.json package-lock.json ./ RUN npm install # 拷贝源码后执行构建 COPY . . RUN npm run build # 阶段二：运行 FROM nginx:1.27-alpine # 从构建阶段拷贝产物到 Nginx 的 HTML 根目录 COPY --from=build /app/dist /usr/share/nginx/html # 用自定义 Nginx 配置覆盖默认配置 COPY nginx.conf /etc/nginx/conf.d/default.conf EXPOSE 80 CMD ["nginx", "-g", "daemon off;"]

COPY package.json package-lock.json ./在COPY . .之前单独提出来，是因为 Docker 构建镜像时，只要某层指令没有变化，就不会重新执行。日常开发中，源码改动远比你换依赖频繁；依赖层被缓存后，每次构建都能省下npm install的时间。我第一次优化这个顺序之后，镜像构建时间从 3 分钟降到了 30 秒左右，属于性价比极高的优化。

daemon off让 Nginx 以前台进程方式运行。Docker 容器里没有一个守护进程持续在前台运行，容器就会立刻退出。这也是新手最容易犯的错误，把 Nginx 用systemctl start nginx的思维去启动，容器起来就自杀。正确姿势是让 Nginx 留在前台。

3.3 nginx.conf 初次登场：给一个能跑的最小配置

先给一个最小可用配置，后面第 5 章再深入讲三个大坑。

server { listen 80; server_name localhost; root /usr/share/nginx/html; index index.html; location / { try_files $uri $uri/ /index.html; } }

这个配置已经能让 CSR 项目通过首页和前端路由访问了。try_files那句是灵魂：先按用户请求的 URL 去找真实文件，找不到就回退到/index.html，把路由解析权交回给前端。如果你只是想让项目“先跑起来”，这个配置就够了。

4. 本地起容器：docker run、Compose 和前后端联调

4.1 docker run 最小启动命令，先把镜像跑起来

镜像构建成功后，启动就非常简单：

docker build -t my-csr-frontend . docker run -d --name frontend-demo -p 8080:80 my-csr-frontend

-p 8080:80表示把容器内 Nginx 的 80 端口映射到宿主机的 8080。浏览器访问http://localhost:8080就能看到项目。这个映射关系是最容易绕晕的点：左侧是你电脑的端口，右侧是容器内的端口。容器内的端口永远由你镜像里的服务决定，容器外的端口则可以根据需要任意调整。

如果启动后页面打不开，先检查两件事。第一，docker ps看容器是否在运行；第二，docker logs frontend-demo看 Nginx 是否报错。端口映射没问题、容器在跑、日志正常，页面一定能开。如果容器启动后几秒就退出，最大概率是 Nginx 前台启动问题，这就用到前面写的daemon off了。

4.2 用 docker-compose 管理前端与后端

本地部署很少有只跑一个纯前端项目的场景。一个典型的人力资源后台管理系统，通常是前端 + 后端 API + MySQL，三个服务要能互相通信。docker run一条条敲很快就失控，docker-compose.yml能把服务编排固化下来。

services: frontend: build: . ports: - "8080:80" environment: - API_BASE_URL=/api api: image: node:20-alpine working_dir: /app volumes: - ./server:/app command: sh -c "npm install && npm run start" ports: - "3000:3000" mysql: image: mysql:8.0 environment: MYSQL_ROOT_PASSWORD: root123 MYSQL_DATABASE: ihrm ports: - "3306:3306" volumes: - mysql-data:/var/lib/mysql volumes: mysql-data:

这里最关键的是 Docker Compose 内置的 DNS 解析：同一份docker-compose.yml内的服务可以通过服务名互相访问。前端容器在 Nginx 配置里写proxy_pass http://api:3000，而不是http://localhost:3000，因为这个api是 Compose 自动解析的内部地址。用localhost反而连不通，因为容器内的localhost指向的是容器自己。

4.3 本地联调：host.docker.internal 与代理转发

本地联调还有一种常见情况：后端不在 Docker 里，而是直接在宿主机上跑，你只把前端容器化。容器内访问宿主机服务，要用一个特殊主机名，以 Docker Desktop 为例是host.docker.internal。Nginx 代理指向它即可：

location /api/ { proxy_pass http://host.docker.internal:3000/; proxy_set_header Host $host; }

注意proxy_pass末尾的斜杠。http://host.docker.internal:3000/会去掉/api前缀转发，而后端接口路径里一般不带/api。不带斜杠则保留原路径。这两种语义我搞混过不止一次，建议你在配置里用一行注释标清楚“要不要去掉前缀，取决于后端接口设计”。

5. CSR 部署三座大山：路由回退、运行时变量、缓存策略

5.1 刷新 404 的根因与标准解

这是 CSR 项目容器化后被问到最多的问题：打开首页正常，点路由跳转也正常，一按 F5 刷新就 404。原因前面说过，Nginx 按文件路径找真实文件，找不到就返回 404。解法则是一条try_files：

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

这条指令的意思是：先按当前 URL 找文件，再试目录，都不存在就回退到/index.html。我把这个配置称为 CSR 项目的“生命线”。有些同学会在各个子路由对应的location块里写重复配置，完全没必要，一个根location块就够了。还有一点要注意，try_files的回退目标必须是/index.html而非/，否则会陷入内部重定向循环，日志里会出现大量 500。

5.2 运行时环境变量注入：两种方案与我的选型

CSR 项目有个特殊痛点：VITE_API_BASE_URL这类变量在npm run build时就被打进静态文件了。这意味着假如你构建了一份指向测试环境的包，想拿到生产环境去换变量，需要重新构建。本地部署时，这种“一环境一构建”的方法非常不灵活。

业界常用的有两种运行时注入方案。第一种是 Nginxsub_filter替换模板占位符。在源码的index.html里保留一句：

<script> window.__RUNTIME_CONFIG__ = {}; </script>

构建产物里这句话还在，Nginx 在响应时动态替换：

location / { sub_filter 'window.__RUNTIME_CONFIG__ = {}' 'window.__RUNTIME_CONFIG__ = {"apiBaseUrl":"$ENV_API_BASE_URL"}'; sub_filter_once on; sub_filter_types text/html; }

启动容器时传环境变量：

docker run -d --name frontend -p 8080:80 \ -e ENV_API_BASE_URL=http://api.example.com \ my-csr-frontend

第二种方案是启动时生成config.js。在镜像里放一个脚本，容器启动时把环境变量写入/usr/share/nginx/html/config.js，然后index.html里<script src="/config.js"></script>。运行时环境变量注入的价值在于：同一份镜像，通过不同的-e参数就能适配测试、预发、生产不同环境，本地和线上保持完全一致。

我个人更推荐第一种sub_filter方案。它不依赖额外脚本，配置直观，而且不需要动index.html的脚本加载顺序。但请注意，sub_filter默认只处理text/html，如果你把配置写在 JS 文件里，需要额外声明sub_filter_types text/javascript application/javascript。我之前在一份压缩混淆过的 JS 里做替换，结果变量名被压缩器重命名，导致替换不生效，排错花了快一个小时。这就是为什么把占位符放在index.html最稳妥，HTML 是构建时唯一不会被混淆的文件。

5.3 静态资源缓存：发布更新与旧文件

CSR 部署最后一个坑是缓存。打包工具的产物通常长这样：index.html不带 hash，assets/index-abc123.js带内容 hash。正确策略是：带 hash 的文件永久缓存，index.html禁用缓存或者极短缓存。否则发完新版本，用户浏览器还在用旧的index.html，引用旧的 JS 脚本。

对应的 Nginx 配置：

location /assets/ { expires 1y; add_header Cache-Control "public, max-age=31536000, immutable"; } location / { add_header Cache-Control "no-cache"; try_files $uri $uri/ /index.html; }

这个配置我实测下来效果稳定：首次访问加载完整资源，之后刷新浏览器几乎不重复下载assets文件，发布新版本后index.html每次都重新校验，用户能及时拿到新壳，新壳再引用新 hash 的资源。如果你在本地部署改了代码却总看不到效果，多半不是 Docker 的问题，而是index.html被缓存了。

注意：location /assets/只对构建产物输出到assets目录生效。如果你的 Vue 项目把 JS 输出到了别的目录，把路径换成对应的实际目录。

6. 本地排错实录：权限拒绝、镜像拉不动、容器秒退

6.1 连不上 Docker API：最常见的第一个报错

第一次在本机跑docker ps，很多人会看到类似permission denied while trying to connect to the Docker daemon socket的报错。含义是当前用户没有访问 Docker 守护进程的权限。Linux 下标准解法是把当前用户加入docker用户组：

sudo usermod -aG docker $USER newgrp docker

然后重新执行docker ps验证。如果你用的是 Docker Desktop，这类权限问题一般不会出现，更多是桌面应用本身没启动。启动 Docker Desktop 后，窗口右下角显示引擎图标变成绿色，命令才能正常执行。一个小提示：有时候docker命令能查到版本，但执行操作报连接失败，八成是守护进程没起来，桌面端重启一下就好。

6.2 镜像拉取缓慢与配置镜像源

本地部署最摧残耐心的环节就是构建镜像时拉基础镜像和依赖包。基础镜像动辄几十兆，网络状况稍差就卡到怀疑人生。常规解法是在 Docker 引擎配置里添加镜像仓库地址。以 Docker Desktop 为例，在 Settings 的 Docker Engine 配置项里编辑daemon.json：

{ "registry-mirrors": ["https://docker.m.daocloud.io"] }

保存后引擎会自动重启。这里的本质是给你的docker pull换一个网络上更快的源，并不影响镜像本身的兼容性。实测下来，基础镜像拉取速度能提升数倍到几十倍，强烈建议所有本地开发者都提前配好。另外npm install阶段也可以加上 npm 镜像源，在 Dockerfile 里写成：

RUN npm install --registry=https://registry.npmmirror.com

6.3 容器启动后秒退：先看日志，再查退出码

容器启动后立刻退出，是最常见且最容易自己解决的排错问题。操作顺序非常重要，不要先去猜问题，先执行：

docker logs 容器ID或名称

这一段大概率会把真正的错误原因直接打出来。比如 Nginx 配置里有一处语法错误，日志会精确到行；端口被占用，报错信息里也会写得很明白；如果日志没有输出，那就查退出码。

退出码 0，说明程序正常结束，去找为什么程序主动退出了，比如镜像里没有前台进程，也就是没有daemon off之类的配置。退出码非 0，说明程序异常，日志里一般会有堆栈信息。这两个方向能覆盖九成以上的“容器秒退”问题。另外docker ps -a能查到已退出容器的状态，docker rm清掉后重新跑，不要舍不得删，容器本身就是一次性的。

7. 这套 Docker 技能还能干的活：开发库与本地 AI 服务

7.1 用同样的镜像思想搭建本地 MySQL 和 Redis

CSR 前端项目容器化跑通后，你会发现这套技术覆盖面比想象的大。最常见的延伸是数据基础设施本地化。比如你要在本地模拟一套完整后端，用 Docker 起 MySQL 和 Redis，不需要自己安装维护：

docker run -d --name dev-mysql -p 3306:3306 \ -e MYSQL_ROOT_PASSWORD=root123 \ -v mysql-data:/var/lib/mysql \ mysql:8.0 docker run -d --name dev-redis -p 6379:6379 redis:7-alpine

-v mysql-data:/var/lib/mysql是数据卷，把 MySQL 的数据保存在宿主机上，容器删了重建数据还在。这个习惯一定要养起来，不然容器一删，数据库里的数据全没了，这个后果比任何缓存问题都严重。

7.2 本地部署 AI 应用：其实也是同一套思路

这些年本地部署 AI 相关的工具越来越火。无论是拉起一个 Ollama 容器来跑大语言模型，还是跑各类开源工具的 Web 服务，背后全是 Docker 的同一套操作：拉镜像、起容器、映射端口、挂数据卷。比如常见的：

docker run -d -v ollama:/root/.ollama -p 11434:11434 ollama/ollama

这和部署前端项目是不是长得一模一样？换了个镜像名，换了个端口，其余的核心思路完全没变。这也是为什么我强烈建议前端同学把 Docker 本地部署这套流程吃透，一旦你掌握了这层抽象，以后面对任何需要本地跑的服务，你会比那些只会双击安装包的人从容得多，因为你在操作“环境”，而不是在操作“安装流程”。

7.3 要不要把所有项目都容器化：我的取舍

最后说一点个人取舍。我不是让所有项目都无脑容器化。日常写 demo、做小练习，npm run dev依然是最快的路径。但一旦项目要交付给他人、要进入联调阶段、要部署到多套环境，容器化几乎没有例外都会用上。我的判断标准很简单：这个项目“环境”是否可能在某天成为别人的困扰。如果是，就别犹豫，尽早把 Dockerfile 和 compose 写出来。

我个人在实际操作中的体会是：本地部署 CSR 前端项目的完整流程，真正难的不是 Docker 命令，而是把“静态托管 + 路由回退 + 运行时变量 + 缓存策略”这几个概念串成一条线。Docker 只是把这条线固化下来，成为可复用的设施。你只需要在这条线上多踩两次坑，之后任何前端项目的部署，对你来说就是改改配置、敲敲命令的事。如果你正卡在某个部署报错上，不妨回头看一眼日志，大多数问题的答案都已经写在那里了。