# 前端环境与结构

<!-- Copyright (c) 2021-2026 小蚂蚁云团队 版权所有 -->

:::tip 说明
前端基于 Vue3 + Ant Design Vue 构建，使用 pnpm 作为包管理工具，Vite 作为构建工具，TypeScript 作为开发语言。
:::

## 技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Vue | 3.x | 渐进式 JavaScript 框架，组合式 API |
| Ant Design Vue | 3.x | Vue3 组件库 |
| Vite | 3.x | 下一代前端构建工具 |
| Pinia | 2.x | 状态管理（Vuex 替代方案） |
| Vue Router | 4.x | 路由管理 |
| Axios | 1.x | HTTP 请求库 |
| TypeScript | 5.x | 类型安全的 JavaScript 超集 |
| Tailwind CSS | 3.x | 原子化 CSS 框架 |
| SCSS | - | CSS 预处理器 |

## 目录结构

```
ui/
├── src/
│ ├── api/          # API 接口定义
│ │ ├── common/     # 公共接口（login、menu、user）
│ │ └── tool/       # 业务模块接口（example 等）
│ ├── assets/       # 静态资源（图片、字体等）
│ ├── components/   # 公共组件（Table、Form、Modal 等）
│ ├── directives/   # 自定义指令（v-perm 权限指令）
│ ├── hooks/        # 组合式函数
│ ├── layout/       # 布局组件
│ ├── router/       # 路由配置（generator-routers、router-guards）
│ ├── store/        # Pinia 状态管理
│ │ └── modules/    # Store 模块（user、asyncRoute、projectSetting 等）
│ ├── styles/       # 全局样式（SCSS 变量、Tailwind）
│ ├── utils/        # 工具函数（http、auth、Storage、dateUtil）
│ │ └── http/axios/ # Axios 封装（VAxios 类、拦截器、取消请求）
│ └── views/        # 页面视图
│ └── tool/         # 业务模块页面（example 等）
├── build/          # 构建配置（vite 插件、常量、工具函数）
├── public/         # 公共静态资源
├── vite.config.ts  # Vite 配置
├── tsconfig.json   # TypeScript 配置
└── package.json    # 依赖配置
```

## 启动开发

```bash
# 安装依赖
pnpm install

# 启动开发服务器（默认端口 8001）
pnpm dev

# 构建生产版本
pnpm build

# 类型检查
pnpm type:check

# 代码检查
pnpm lint:eslint && pnpm lint:prettier && pnpm lint:stylelint
```

## Vite 配置

`vite.config.ts` 是 Vite 的核心配置文件，实际配置如下：

```typescript
import type { UserConfig, ConfigEnv } from 'vite';
import { loadEnv } from 'vite';
import { resolve } from 'path';
import { wrapperEnv } from './build/utils';
import { createVitePlugins } from './build/vite/plugin';
import { OUTPUT_DIR } from './build/constant';
import { createProxy } from './build/vite/proxy';

export default ({ command, mode }: ConfigEnv): UserConfig => {
    const root = process.cwd();
    const env = loadEnv(mode, root);
    const viteEnv = wrapperEnv(env);
    const { VITE_PUBLIC_PATH, VITE_PORT, VITE_GLOB_PROD_MOCK } = viteEnv;

    let VITE_PROXY: any = viteEnv.VITE_PROXY;
    if (!VITE_PROXY) {
        VITE_PROXY = '[[]]';
    }
    try {
        if (typeof VITE_PROXY === 'string') {
            VITE_PROXY = JSON.parse(VITE_PROXY);
        }
    } catch (e) {
        VITE_PROXY = [[]];
    }

    const isBuild = command === 'build';

    return {
        base: VITE_PUBLIC_PATH,
        resolve: {
            alias: [
                { find: '@', replacement: pathResolve('src') + '/' },
            ],
            dedupe: ['vue'],
        },
        plugins: createVitePlugins(viteEnv, isBuild, prodMock),
        css: {
            preprocessorOptions: {
                scss: {
                    additionalData: `@import "src/styles/var.scss";`,
                },
            },
        },
        server: {
            host: true,
            port: VITE_PORT,
            proxy: createProxy(VITE_PROXY),
        },
        build: {
            target: 'es2015',
            outDir: OUTPUT_DIR,
            reportCompressedSize: false,
            chunkSizeWarningLimit: 2000,
        },
    };
};
```

关键配置说明：

- `@` 别名指向 `src/` 目录，代码中可用 `@/api/tool/example` 引入模块
- SCSS 全局变量通过 `additionalData` 注入，无需每个文件手动 `@import`
- 代理配置通过 `VITE_PROXY` 环境变量传入，由 `createProxy()` 工具函数解析
- 构建产物输出到 `OUTPUT_DIR`（默认 `dist/`）

## 应用入口

`src/main.ts` 是应用入口，负责初始化所有基础设施：

```typescript
import { createApp } from 'vue';
import App from './App.vue';
import router, { setupRouter } from './router';
import { setupStore } from '@/store';
import { setupElement, setupDirectives, setupCustomComponents } from '@/plugins';

async function bootstrap() {
    const app = createApp(App);

    setupAntd(app);                 // 全局引入 Ant Design Vue 组件
    setupCustomComponents(app);     // 注册自定义组件
    setupDirectives(app);           // 注册自定义指令（v-perm 等）
    setupStore(app);                // 挂载 Pinia 状态管理
    await setupRouter(app);         // 挂载路由
    await router.isReady();         // 路由准备就绪

    app.mount('#app', true);
}

void bootstrap();
```

初始化顺序：样式加载 -> Ant Design Vue -> 自定义组件 -> 自定义指令 -> Pinia Store -> Router -> 挂载。

## 总结

前端项目基于 Vue3 + Ant Design Vue + Vite + TypeScript + Pinia 构建，使用 pnpm 管理依赖，Tailwind CSS + SCSS 提供样式能力。通过 `main.ts` 的 `bootstrap()` 函数按顺序初始化所有基础设施，目录结构按功能分层组织，便于维护和扩展。