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`

## 构建命令

```bash
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 参考配置

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