haoliang-net/docs/frontend-build-deploy.md

前端构建与部署规范

构建输出配置

配置项	值	说明
base	/admin/	构建时资源引用路径前缀
outDir	src/CncWebApi/admin	构建产物输出目录
emptyOutDir	true	允许清空目标目录

IIS 部署结构

E:\opencode\haoliang\src\CncWebApi\        ← IIS站点根目录
├── admin\                                  ← 前端构建输出
│   ├── index.html
│   ├── assets\
│   ├── favicon.svg
│   └── icons.svg
├── api\                                    ← 后端API
├── bin\                                    ← 后端DLL
└── ...other backend files...

资源路径映射

• 浏览器访问 /admin/login → IIS物理路径 E:\opencode\haoliang\src\CncWebApi\admin\index.html
• 前端资源引用 /admin/assets/xxx.js → IIS物理路径 E:\opencode\haoliang\src\CncWebApi\admin\assets\xxx.js

构建命令

cd frontend
npm run build

部署检查清单

1. ✅ vite.config.ts 的 base 必须为 /admin/
2. ✅ vite.config.ts 的 outDir 必须指向 src/CncWebApi/admin
3. ✅ IIS 站点物理路径必须为 E:\opencode\haoliang\src\CncWebApi
4. ✅ 构建后 src/CncWebApi/admin/index.html 存在
5. ✅ 构建后 src/CncWebApi/admin/assets/ 目录存在

常见问题

资源404

• 症状：页面能加载，但 JS/CSS 返回 404
• 原因：base 配置与 IIS 物理路径不匹配
• 检查：浏览器 DevTools Network 面板，JS 引用路径是否为 /admin/assets/xxx.js

页面404

• 症状：首页能加载，但路由（如 /admin/dashboard）返回 404
• 原因：IIS 缺少 URL Rewrite 规则，需配置通配符路由 fallback
• 检查：src/CncWebApi/Web.config 是否存在且配置正确

vite.config.ts 参考配置

export default defineConfig(({ command }) => ({
  // build时部署到/admin/子路径，dev时用根路径
  base: command === 'build' ? '/admin/' : '/',
  build: {
    outDir: path.resolve(__dirname, '../src/CncWebApi/admin'),
    emptyOutDir: true,
  },
}))