（六）打包优化 + Nginx 部署完整配置 + 项目收尾

前面已经完成业务、布局、权限、mock 切换。本节完成：vite 打包优化、dist 产物说明、nginx 配置、部署常见坑、项目目录总览、后续扩展方向。

一、vite.config.js 增加打包优化配置

修改根目录 vite.config.js，增加构建分包、压缩配置

复制代码

import { defineConfig, loadEnv } from 'vite'
import vue from '@vitejs/plugin-vue'
import { viteMockServe } from 'vite-plugin-mock'
import path from 'path'

// https://vitejs.dev/config/
export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd())
  return {
    plugins: [
      vue(),
      viteMockServe({
        mockPath: 'src/mock',
        enable: env.VITE_USE_MOCK === 'true',
        localEnabled: env.VITE_USE_MOCK === 'true',
        prodEnabled: false
      })
    ],
    resolve: {
      alias: {
        '@': path.resolve(__dirname, './src')
      }
    },
    server: {
      port: 5173,
      open: true,
      proxy: {
        '/api': {
          target: 'http://127.0.0.1:3000',
          changeOrigin: true,
          rewrite: path => path.replace(/^\/api/, '')
        }
      }
    },
    build: {
      // 打包后资源输出目录，默认dist
      outDir: 'dist',
      assetsDir: 'static',
      // 小于此阈值的资源转为base64
      assetsInlineLimit: 4096,
      // 分包策略，拆分第三方库
      rollupOptions: {
        output: {
          manualChunks: {
            'vue-vendor': ['vue', 'vue-router', 'pinia'],
            'element-plus': ['element-plus']
          }
        }
      }
    }
  }
})

二、环境变量补充说明

.env.development 只在 pnpm dev 开发模式生效

.env.production 只在 pnpm build 打包生产模式生效

.env.production

复制代码

#生产环境，mock关闭，全部请求后端真实接口
VITE_USE_MOCK=false
#生产后端接口前缀，根据你的后端实际地址修改
VITE_API_BASE_URL=/api

⚠️重要：生产环境vite 的 server.proxy 代理不生效 ！代理只存在开发环境。

生产环境接口地址两种方案：

前端写 /api，交给 Nginx 反向代理转发后端（推荐）
VITE_API_BASE_URL = "http://后端真实域名/api"（注意后端要处理跨域）

三、执行打包

复制代码

pnpm build

打包完成根目录生成 dist 文件夹，这个就是最终部署的全部静态文件。

本地预览打包产物：

复制代码

pnpm preview

四、Nginx 部署完整配置（重点）

dist 文件夹上传服务器，放到 nginx 网站根目录。

nginx.conf 核心配置

复制代码

server {
    listen 80;
    server_name 你的域名或者服务器ip;

    #前端静态资源根目录，指向dist文件夹
    root /usr/share/nginx/html/admin-dist;
    index index.html;

    #解决vue history模式刷新404！必须配置
    location / {
        try_files $uri $uri/ /index.html;
    }

    #生产接口反向代理，把前端 /api 请求转发到后端服务
    location /api {
        proxy_pass http://127.0.0.1:3000; #你的后端服务地址
        proxy_set_header Host $host;
        proxy_set_header X‑Real‑IP $remote_addr;
        proxy_set_header X‑Forwarded‑For $proxy_add_x_forwarded_for;
    }

    #静态资源缓存
    location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ {
        expires 7d;
    }
}

部署高频踩坑

页面刷新 404 ：try_files $uri $uri/ /index.html; 必须写，history 模式 vue 必备
生产环境接口 404 ：开发环境 proxy 只本地有效，生产靠 nginx 的location /api反向代理
接口跨域：不要前端写全后端域名，优先 nginx 代理
打包后页面空白 ：检查 vite build 的base，如果部署在子目录，需要配置base:'./'

如果部署在子目录，例如 http://xxx/admin，vite.config build 下增加 base:'./'

五、完整项目目录总览

复制代码

admin‑vue3‑js
├── .env.development        #开发环境变量
├── .env.production         #生产环境变量
├── .gitignore
├── index.html
├── package.json
├── vite.config.js
└── src
    ├── api                 #接口请求函数
    │   └── user.js
    ├── assets              #静态资源
    ├── components          #公共组件
    │   ├── Breadcrumb.vue  #面包屑
    │   └── TagsView.vue    #多标签页
    ├── layout              #后台外壳布局
    │   └── index.vue
    ├── mock                #mock模拟接口
    │   └── user.js
    ├── router              #路由
    │   └── index.js
    ├── stores              #pinia状态
    │   ├── app.js
    │   └── user.js
    ├── utils               #工具
    │   ├── permission.js   #权限工具
    │   └── request.js      #axios封装
    ├── views               #页面
    │   ├── home
    │   │   └── index.vue
    │   ├── login
    │   │   └── index.vue
    │   └── userManage
    │       └── index.vue
    ├── App.vue
    └── main.js

六、项目完整功能汇总

pnpm + Vite + Vue3 JS，不使用 TS，零基础可上手
Element‑Plus 后台管理整套 UI
MockJS 本地模拟接口，一键切换 mock / 真实后端接口
Axios 统一封装：请求拦截、响应拦截、token 处理、401 过期跳转登录、错误统一提示
Pinia 状态管理，用户状态、布局状态（侧边栏折叠、标签页）
Vue‑Router4 history 模式、路由守卫
登录、退出登录、token 本地存储
Layout 布局：侧边栏可折叠、头部、面包屑导航、TagsView 多标签页
用户管理模块：搜索、分页、新增、编辑、删除、表单校验、弹窗确认
自定义指令实现按钮级别权限控制
vite 打包优化，分包拆分
Nginx 完整部署配置，解决 history 刷新 404，接口反向代理

七、开发常用命令速查表

复制代码

pnpm install        #安装全部依赖
pnpm dev            #启动开发环境（可mock）
pnpm build          #打包生产dist
pnpm preview        #本地预览打包产物

八、后续拓展建议（可选，不再贴大段代码）

动态路由：后端返回菜单 JSON，前端动态 addRoute 渲染侧边栏菜单
文件上传组件：模拟上传 mock，对接后端上传接口
Excel 导入导出（xlsx 库）
全局 svg 图标封装
全局弹窗封装，二次确认组件
页面缓存 keep‑alive