docs/v1.0/requirements/frontend/03-build-environment.md

构建与开发环境

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

---

目录

1. 环境变量
2. 环境变量类型定义
3. 开发脚本
4. Vite 配置

---

1. 环境变量

1.1 开发环境

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

1.2 生产环境

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

1.3 测试环境

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

---

2. 环境变量类型定义

// 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 使用环境变量

// 在代码中使用
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 脚本

{
  "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 常用命令

# 安装依赖
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 基础配置

// 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 代码分割策略

// 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 环境特定配置

// 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,
    },
  };
});

---

相关文档

• 技术栈概览
• 项目结构
• 部署方案

---

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