# 构建与开发环境

> **文档版本**：v1.1  
> **最后更新**：2025-01-18

---

## 目录

1. [环境变量](#1-环境变量)
2. [环境变量类型定义](#2-环境变量类型定义)
3. [开发脚本](#3-开发脚本)
4. [Vite 配置](#4-vite-配置)

---

## 1. 环境变量

### 1.1 开发环境

```bash
# .env.development
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_USE_MOCK=true
VITE_APP_TITLE=Jointo（开发）
```

### 1.2 生产环境

```bash
# .env.production
VITE_API_BASE_URL=https://api.jointo.ai/api/v1
VITE_USE_MOCK=false
VITE_APP_TITLE=Jointo
```

### 1.3 测试环境

```bash
# .env.staging
VITE_API_BASE_URL=https://staging-api.jointo.ai/api/v1
VITE_USE_MOCK=false
VITE_APP_TITLE=Jointo（测试）
```

---

## 2. 环境变量类型定义

```typescript
// src/vite-env.d.ts
/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_API_BASE_URL: string;
  readonly VITE_USE_MOCK: string;
  readonly VITE_APP_TITLE: string;
}

interface ImportMeta {
  readonly env: ImportMetaEnv;
}
```

### 2.1 使用环境变量

```typescript
// 在代码中使用
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL;
const useMock = import.meta.env.VITE_USE_MOCK === "true";
const appTitle = import.meta.env.VITE_APP_TITLE;

// 示例：API 客户端配置
import axios from "axios";

const apiClient = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,
  timeout: 30000,
});
```

---

## 3. 开发脚本

### 3.1 package.json 脚本

```json
{
  "scripts": {
    "dev": "vite",
    "build": "tsc -b && vite build",
    "build:staging": "tsc -b && vite build --mode staging",
    "preview": "vite preview",
    "lint": "eslint .",
    "lint:fix": "eslint . --fix",
    "format": "prettier --write \"src/**/*.{ts,tsx,css,json}\"",
    "type-check": "tsc --noEmit"
  }
}
```

### 3.2 脚本说明

| 脚本            | 说明                | 使用场景         |
| --------------- | ------------------- | ---------------- |
| `dev`           | 启动开发服务器      | 本地开发         |
| `build`         | 生产环境构建        | 部署到生产环境   |
| `build:staging` | 测试环境构建        | 部署到测试环境   |
| `preview`       | 预览生产构建        | 本地验证构建产物 |
| `lint`          | 代码检查            | CI/CD 流程       |
| `lint:fix`      | 自动修复代码问题    | 开发时修复问题   |
| `format`        | 代码格式化          | 统一代码风格     |
| `type-check`    | TypeScript 类型检查 | CI/CD 流程       |

### 3.3 常用命令

```bash
# 安装依赖
npm install

# 启动开发服务器（默认端口 5173）
npm run dev

# 构建生产版本
npm run build

# 预览生产构建
npm run preview

# 代码检查并自动修复
npm run lint:fix

# 格式化所有代码
npm run format

# 类型检查
npm run type-check
```

---

## 4. Vite 配置

### 4.1 基础配置

```typescript
// vite.config.ts
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import tailwindcss from "@tailwindcss/vite";
import path from "path";

export default defineConfig({
  plugins: [react(), tailwindcss()],

  resolve: {
    alias: {
      "@": path.resolve(__dirname, "./src"),
      "@components": path.resolve(__dirname, "./src/components"),
      "@hooks": path.resolve(__dirname, "./src/hooks"),
      "@stores": path.resolve(__dirname, "./src/stores"),
      "@services": path.resolve(__dirname, "./src/services"),
      "@types": path.resolve(__dirname, "./src/types"),
      "@utils": path.resolve(__dirname, "./src/utils"),
      "@constants": path.resolve(__dirname, "./src/constants"),
      "@assets": path.resolve(__dirname, "./src/assets"),
    },
  },

  server: {
    port: 5173,
    host: true,
    open: true,
  },

  build: {
    outDir: "dist",
    sourcemap: false,
    rollupOptions: {
      output: {
        manualChunks: {
          "react-vendor": ["react", "react-dom", "react-router-dom"],
          "ui-vendor": [
            "@radix-ui/react-dialog",
            "@radix-ui/react-dropdown-menu",
          ],
          "query-vendor": ["@tanstack/react-query"],
        },
      },
    },
  },
});
```

### 4.2 配置说明

#### Plugins

- `react()`: React 支持，包括 Fast Refresh
- `tailwindcss()`: Tailwind CSS v4 支持

#### Resolve

- `alias`: 路径别名配置，简化导入路径

#### Server

- `port`: 开发服务器端口（默认 5173）
- `host`: 允许外部访问
- `open`: 自动打开浏览器

#### Build

- `outDir`: 构建输出目录
- `sourcemap`: 是否生成 source map
- `manualChunks`: 手动分包，优化加载性能

---

## 5. 构建优化

### 5.1 代码分割策略

```typescript
// vite.config.ts
export default defineConfig({
  build: {
    rollupOptions: {
      output: {
        manualChunks: {
          // React 核心库
          "react-vendor": ["react", "react-dom", "react-router-dom"],

          // UI 组件库
          "ui-vendor": [
            "@radix-ui/react-dialog",
            "@radix-ui/react-dropdown-menu",
            "@radix-ui/react-select",
            "@radix-ui/react-tabs",
          ],

          // 数据请求库
          "query-vendor": ["@tanstack/react-query"],

          // 状态管理
          "state-vendor": ["zustand"],

          // 工具库
          "utils-vendor": ["axios", "date-fns", "zod"],
        },
      },
    },
  },
});
```

### 5.2 环境特定配置

```typescript
// vite.config.ts
import { defineConfig, loadEnv } from "vite";

export default defineConfig(({ mode }) => {
  const env = loadEnv(mode, process.cwd(), "");

  return {
    // ... 其他配置

    define: {
      __APP_VERSION__: JSON.stringify(process.env.npm_package_version),
    },

    build: {
      sourcemap: mode === "development",
      minify: mode === "production" ? "esbuild" : false,
    },
  };
});
```

---

## 相关文档

- [技术栈概览](./01-tech-stack.md)
- [项目结构](./02-project-structure.md)
- [部署方案](./12-deployment.md)

---

**最后更新**：2025-01-18 | **版本**：v1.1