第 1 章：项目初始化与技术选型

本章学习目标

理解为什么选择 React 19 + TypeScript + Vite 技术栈
从零搭建一个企业级前端项目脚手架
掌握目录结构设计的思路
学会配置 ESLint、Prettier 和路径别名
了解多环境配置方案
接入 Ant Design 组件库

1.1 为什么选这套技术栈

在开始写代码之前，我们先聊聊技术选型的思考。

React 19

React 19 带来了很多新特性，对后台系统开发特别友好：

useOptimistic：乐观更新，提升操作反馈体验
useActionState：表单处理更简洁
ref 作为 prop：不再需要 forwardRef 包裹
Server Components：复杂场景下的性能优化手段

TypeScript

后台系统的核心痛点是数据模型复杂 、字段多 、状态流转繁琐。TypeScript 能在编译期就发现大量 Bug，是企业级项目的必选项。

Vite

相比 Webpack，Vite 的开发体验提升明显：

冷启动快：基于 ESM，不需要打包整个项目
HMR 快：模块级热更新，改完代码秒级刷新
配置简单：开箱即用，插件生态成熟

Ant Design 5.x

企业级后台最常用的组件库，没有之一：

组件丰富（表格、表单、弹窗、树...应有尽有）
设计规范统一
主题定制方便（CSS-in-JS）
TypeScript 支持好

1.2 从零搭建项目脚手架

1.2.1 初始化 Vite 项目

bash 复制代码

npm create vite@latest admin-hub -- --template react-ts
cd admin-hub
npm install

1.2.2 安装基础依赖

bash 复制代码

# 路由
npm install react-router-dom

# HTTP 请求
npm install axios

# UI 组件库
npm install antd @ant-design/icons

# 图表
npm install echarts echarts-for-react

# 工具库
npm install dayjs lodash-es

# 开发依赖 - 代码规范
npm install -D eslint prettier eslint-config-prettier eslint-plugin-prettier
npm install -D @typescript-eslint/parser @typescript-eslint/eslint-plugin
npm install -D eslint-plugin-react-hooks eslint-plugin-react-refresh

1.3 目录结构设计

一个清晰的目录结构是项目可维护的基础。推荐以下分层：

bash 复制代码

src/
├── assets/              # 静态资源（图片、字体等）
├── components/          # 通用组件（可跨页面复用）
│   ├── StatCard/        # 统计卡片
│   ├── TimeLine/        # 时间线
│   └── Empty/           # 空状态
├── hooks/               # 自定义 Hooks（跨页面复用的逻辑）
│   ├── usePagination.ts # 分页逻辑
│   ├── useDebounce.ts   # 防抖
│   └── useTable.ts      # 表格通用逻辑
├── layouts/             # 布局组件
│   ├── BasicLayout/     # 基础布局（侧边栏 + 顶栏 + 内容）
│   └── BlankLayout/     # 空白布局（登录页等）
├── pages/               # 页面层（按业务模块划分）
│   ├── workbench/       # 工作台
│   ├── ticket/          # 任务单管理
│   ├── approval/        # 审批管理
│   ├── scheduled-task/  # 定时任务
│   ├── ai-assistant/    # AI 助手
│   ├── knowledge/       # 知识中心
│   └── statistics/      # 数据统计
├── services/            # 服务层（API 调用）
│   ├── request.ts       # axios 实例与拦截器
│   ├── ticket.ts        # 任务单相关接口
│   └── ...
├── store/               # 状态管理
│   ├── createStore.ts   # 轻量 Store 工厂函数
│   ├── useUserStore.ts  # 用户信息（全局）
│   └── useTicketStore.ts# 任务单（页面级）
├── types/               # 类型定义
│   ├── api.ts           # 通用接口类型
│   ├── ticket.ts        # 任务单类型
│   └── ...
├── utils/               # 工具函数
│   ├── format.ts        # 格式化工具
│   ├── storage.ts       # 本地存储封装
│   └── validate.ts      # 校验规则
├── router/              # 路由配置
│   ├── index.tsx        # 路由入口
│   └── routes.ts        # 路由表定义
├── App.tsx              # 根组件
└── main.tsx             # 入口文件

为什么这样分？

目录	职责	特点
pages/	页面容器，组合组件与业务逻辑	按业务模块分，每个模块一个文件夹
components/	纯 UI 组件，不包含业务逻辑	可在任何页面复用
hooks/	逻辑复用单元	抽离状态逻辑，组件只负责渲染
services/	数据获取层	统一管理 API，便于 mock 和切换
store/	状态管理	全局状态放这里，页面级状态尽量用 useState
types/	类型定义	业务类型集中管理，避免循环引用

1.4 配置 ESLint + Prettier + 路径别名

1.4.1 ESLint 配置

在项目根目录创建 .eslintrc.cjs：

javascript 复制代码

module.exports = {
  root: true,
  env: { browser: true, es2021: true, node: true },
  extends: [
    'eslint:recommended',
    'plugin:@typescript-eslint/recommended',
    'plugin:react-hooks/recommended',
    'plugin:prettier/recommended',
  ],
  ignorePatterns: ['dist', '.eslintrc.cjs'],
  parser: '@typescript-eslint/parser',
  parserOptions: {
    ecmaVersion: 'latest',
    sourceType: 'module',
    ecmaFeatures: { jsx: true },
  },
  settings: { react: { version: 'detect' } },
  plugins: ['react-refresh'],
  rules: {
    'react-refresh/only-export-components': [
      'warn',
      { allowConstantExport: true },
    ],
    '@typescript-eslint/no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
    '@typescript-eslint/no-explicit-any': 'warn',
  },
};

1.4.2 Prettier 配置

创建 .prettierrc：

json 复制代码

{
  "semi": true,
  "singleQuote": true,
  "trailingComma": "all",
  "printWidth": 100,
  "tabWidth": 2,
  "arrowParens": "always"
}

1.4.3 路径别名

Vite 配置 vite.config.ts：

typescript 复制代码

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import path from 'path';

export default defineConfig({
  plugins: [react()],
  resolve: {
    alias: {
      '@': path.resolve(__dirname, 'src'),
      '@components': path.resolve(__dirname, 'src/components'),
      '@hooks': path.resolve(__dirname, 'src/hooks'),
      '@services': path.resolve(__dirname, 'src/services'),
      '@store': path.resolve(__dirname, 'src/store'),
      '@utils': path.resolve(__dirname, 'src/utils'),
      '@pages': path.resolve(__dirname, 'src/pages'),
      '@types': path.resolve(__dirname, 'src/types'),
    },
  },
});

同步配置 tsconfig.json 的 compilerOptions：

json 复制代码

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@components/*": ["src/components/*"],
      "@hooks/*": ["src/hooks/*"],
      "@services/*": ["src/services/*"],
      "@store/*": ["src/store/*"],
      "@utils/*": ["src/utils/*"],
      "@pages/*": ["src/pages/*"],
      "@types/*": ["src/types/*"]
    }
  }
}

1.5 环境变量与多环境配置

后台系统通常有三个环境：开发、测试、生产。

1.5.1 环境变量文件

在项目根目录创建：

env 复制代码

# .env.development ------ 开发环境
VITE_API_BASE_URL=/api
VITE_APP_TITLE=AdminHub (开发环境)

env 复制代码

# .env.staging ------ 测试环境
VITE_API_BASE_URL=https://staging-api.example.com
VITE_APP_TITLE=AdminHub (测试环境)

env 复制代码

# .env.production ------ 生产环境
VITE_API_BASE_URL=https://api.example.com
VITE_APP_TITLE=AdminHub

1.5.2 类型声明

在 src/vite-env.d.ts 中补充类型：

typescript 复制代码

/// <reference types="vite/client" />

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

interface ImportMeta {
  readonly env: ImportMetaEnv;
}

1.5.3 package.json 脚本

json 复制代码

{
  "scripts": {
    "dev": "vite",
    "build:staging": "tsc && vite build --mode staging",
    "build:prod": "tsc && vite build --mode production",
    "preview": "vite preview",
    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
  }
}

1.6 接入 Ant Design 组件库

1.6.1 基础配置

在 App.tsx 中配置全局主题：

tsx 复制代码

import { ConfigProvider, App as AntdApp } from 'antd';
import zhCN from 'antd/locale/zh_CN';
import 'dayjs/locale/zh-cn';
import { RouterProvider } from 'react-router-dom';
import router from './router';

const theme = {
  token: {
    colorPrimary: '#1677ff',
    borderRadius: 6,
    fontFamily: '"PingFang SC", "Microsoft YaHei", sans-serif',
  },
};

function App() {
  return (
    <ConfigProvider locale={zhCN} theme={theme}>
      <AntdApp>
        <RouterProvider router={router} />
      </AntdApp>
    </ConfigProvider>
  );
}

export default App;

为什么用 AntdApp？ Ant Design 5.x 推荐用 App 组件来获取全局的 message、modal、notification 实例，不需要再手动 import 和处理 Context。

1.6.2 按需加载

Ant Design 5.x 默认支持 Tree Shaking，不需要额外配置按需加载插件。直接 import { Button } from 'antd' 即可。

1.7 第一个页面：Hello AdminHub

在 src/pages/demo/Hello.tsx 写一个简单的验证页面：

tsx 复制代码

import { Button, Card, Space, Typography } from 'antd';
import { SmileOutlined } from '@ant-design/icons';

const { Title, Paragraph } = Typography;

export default function Hello() {
  return (
    <div style={{ padding: 24 }}>
      <Card>
        <Space direction="vertical" size="middle" style={{ width: '100%' }}>
          <Title level={2}>
            <SmileOutlined style={{ marginRight: 8 }} />
            欢迎使用 AdminHub
          </Title>
          <Paragraph type="secondary">
            这是你的第一个后台页面。接下来我们会一步步构建完整的管理系统。
          </Paragraph>
          <Button type="primary">开始学习</Button>
        </Space>
      </Card>
    </div>
  );
}

运行 npm run dev，看到页面说明项目搭建成功。

本章小结

知识点	关键内容
技术选型	React 19 + TypeScript + Vite + Ant Design 5.x
目录结构	按职责分层：pages / components / hooks / services / store / utils
代码规范	ESLint 检查代码质量，Prettier 统一格式
路径别名	Vite + TSConfig 双配置，使用 `@/` 替代深层相对路径
多环境	`.env.*` 文件 + `--mode` 参数，三环境隔离
UI 框架	Ant Design 5.x，通过 ConfigProvider 配置主题和语言

下一章预告：我们会深入架构设计，实现一套轻量级状态管理方案，并完成 axios 的统一封装和路由体系搭建。