Vue + Vite 项目部署 Docker 全攻略：原理、路由机制、问题排查与开发代理解析

本文面向希望将 Vue 3 + Vite 项目部署到生产环境（Docker + NGINX）并深入理解路由行为、构建机制与常见问题排查的开发者。

📦 一、项目准备

以 Vue 3 + Vite + Vue Router（history 模式）为基础结构，假设你项目结构如下：

my-app/
├── src/
│   ├── main.ts
│   ├── App.vue
│   └── router/index.ts
├── index.html
├── vite.config.ts
├── Dockerfile
├── nginx.conf
└── ...

🚀 二、构建产物与部署

1. 构建 Vite 项目

运行：

npm run build

生成的 dist 目录即为生产环境静态资源（包含 index.html 和 /assets 目录）。

2. Dockerfile 示例

# 构建阶段
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build# 生产部署阶段
FROM nginx:stable-alpine
COPY nginx.conf /etc/nginx/conf.d/default.conf
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80
CMD ["nginx", "-g", "daemon off;"]

3. NGINX 配置 nginx.conf

必须添加路由 fallback 规则，否则刷新页面会 404：

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

4. 构建并运行容器

docker build -t vue-app .
docker run -d -p 8080:80 vue-app

🔁 三、路由访问原理

以 Vue Router 的 history 模式为例，访问 http://localhost:8080/login 时，完整流程如下：

1. 浏览器发起 GET /login 请求
2. NGINX 未找到 /login.html ⇒ fallback 到 /index.html
3. 浏览器加载 index.html 中的 /assets/index.[hash].js
4. Vue 应用执行，router 检测当前路径为 /login
5. 匹配到 /login 路由，渲染 Login.vue

如图：

Browser ──GET /login────▶ NGINX ──fallback──▶ /index.html│                     │▼                     ▼Vue App 加载          Vue Router 路由解析▼                     ▼渲染 Login.vue     ⇒ Login 页面展示

🧭 四、常见问题与排查

1. 访问 /login 显示 index.html 内容，页面不渲染组件？

可能原因：

App.vue 中未写 <router-view />
Login.vue 模板为空或未正确导出组件
使用了复杂 App.vue 包裹 layout，但 login 页依赖不满足导致 setup 被短路
构建后的 chunk 文件加载失败（JS 路径不对 / base 配置错误）
import(‘…/views/Login.vue’) 懒加载路径大小写错误

建议排查：

console.log in main.ts & Login.vue → 是否执行？
F12 → Network → JS 文件是否 404？
控制台是否有红色错误？
使用 vite preview 验证构建产物是否可用

2. run dev 模式正常，build 后访问失败？

开发模式（vite dev）：

动态模块按需加载，容错强
页面路径自动 fallback
即使 Login.vue 结构有问题，也可能渲染成功

构建模式（vite build）：

静态资源路径必须精确
Vue 模块必须正确导出组件
任一导入错误（如路径拼写、未 export）将导致页面白屏

✅ 为什么 dev 模式能访问 login，而 build 后失败？

这是一个非常常见的问题，其核心原因如下：

比较点	vite dev	vite build（部署后）
模块加载	动态、按需、容错	静态 chunk、路径严格、错误即失败
Vue Router fallback	自动支持 history 模式	需依赖 nginx try_files 配置
模块路径大小写	忽略大小写错误	区分大小写，路径不对即加载失败
setup 异常容忍度	容错强，console 报错但页面仍可加载	setup 异常可能中断组件加载 ⇒ 白屏
异步 import() 失败	console 警告	路由无法 resolve 组件 ⇒ 页面不渲染

举例：

App.vue 中访问 localStorage 中的 user_info，但 login 页并未设置这些字段 ⇒ dev 模式容忍，build 模式直接 setup 错误挂掉；
import(‘@/views/Login.vue’) 写错为 ‘@/Views/Login.vue’，dev 模式不会报错但 build 后 404；
login 页未使用 <router-view /> 包裹，则 dev 模式可能能跑，build 无响应。

解决方案：

使用 layout 分离 login 与主框架页面；
App.vue 中仅保留 <router-view />；
路由组件路径大小写、export default 必须正确；
在 vite preview 中模拟 build 效果进行测试。

🌐 五、代理的作用与使用场景

开发环境中调用 API 常涉及跨域，解决方案是配置 Vite 的代理。

vite.config.ts:

export default defineConfig({server: {proxy: {'/api': {target: 'http://localhost:3000',changeOrigin: true,rewrite: path => path.replace(/^\/api/, '')}}}
})