第 3 章工程化与项目初始化

📌 本章目标：把项目的工程化基础搭好，为后面写业务代码做准备

⭐⭐ 难度：基础 | ⏱️ 预计时间：1 小时

3.1 什么是「工程化」？

先想一个问题

两个程序员一起做项目，怎么保证：

代码风格一致？（有的人用 2 空格缩进，有的人用 4 空格）
不会写出有明显 bug 的代码？
项目能快速启动和打包？
样式变量能统一管理？

这就是工程化要解决的问题：用工具和规范，让项目开发更高效、更稳定、更好协作。

3.2 路径别名：让导入变优雅

为什么需要路径别名？

你可能写过这样的代码：

tsx 复制代码

import Button from '../../../../components/Button';

一层层的 ../ 既难看又容易写错。路径别名 就是解决这个问题的：

tsx 复制代码

import Button from '@/components/Button';

@ 就代表 src 目录，简洁又清晰！

怎么配置？

第一步：配置 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(process.cwd(), './src'),
    },
  },
});

第二步：配置 TypeScript

编辑 tsconfig.json：

json 复制代码

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

💡 小贴士：两边都要配！Vite 管运行时，TypeScript 管类型检查，少一个都不行。

3.3 Less + 全局样式变量

为什么用 Less？

普通 CSS 功能有限，Less 是 CSS 的「升级版」，支持：

变量（统一管理颜色、尺寸）
嵌套（层级结构更清晰）
mixin（可复用的样式片段）
运算（width: 100% - 20px）

安装 Less

bash 复制代码

npm install less -D
# 或者
yarn add less -D

配置全局注入

我们希望每个 .less 文件都能自动用上全局变量，不用每次手动 @import。

编辑 vite.config.ts：

typescript 复制代码

export default defineConfig({
  // ...
  css: {
    preprocessorOptions: {
      less: {
        additionalData(source: string, filePath: string) {
          // node_modules 里的文件不注入，避免性能问题
          if (filePath.includes('node_modules')) return source;
          return `
            @import "@/styles/variables.less";
            @import "@/styles/mixins.less";
          ` + source;
        },
      },
    },
  },
});

创建全局样式文件

创建 src/styles/variables.less：

less 复制代码

// ===== 颜色 =====
@primary-color: #1677ff;
@success-color: #52c41a;
@warning-color: #faad14;
@error-color: #ff4d4f;

// ===== 文字颜色 =====
@text-primary: rgba(0, 0, 0, 0.88);
@text-secondary: rgba(0, 0, 0, 0.65);
@text-disabled: rgba(0, 0, 0, 0.25);

// ===== 背景色 =====
@bg-body: #f5f5f5;
@bg-card: #ffffff;

// ===== 尺寸 =====
@sidebar-width: 280px;
@exec-panel-width: 400px;
@header-height: 56px;

// ===== 圆角 =====
@radius-sm: 4px;
@radius-md: 8px;
@radius-lg: 12px;

// ===== 间距 =====
@spacing-xs: 4px;
@spacing-sm: 8px;
@spacing-md: 16px;
@spacing-lg: 24px;

创建 src/styles/mixins.less：

less 复制代码

// 文字超出省略号
.text-ellipsis() {
  overflow: hidden;
  white-space: nowrap;
  text-overflow: ellipsis;
}

// 弹性布局居中
.flex-center() {
  display: flex;
  align-items: center;
  justify-content: center;
}

// 卡片样式
.card-base() {
  background: @bg-card;
  border-radius: @radius-md;
  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.06);
}

🎯 核心概念：把颜色、尺寸都用变量管理，以后要改主题色，只改一个变量就全站生效。

3.4 安装 Ant Design

Ant Design 是企业级 UI 组件库，按钮、弹窗、表格、表单... 全都有现成的。

bash 复制代码

npm install antd
# 或者
yarn add antd

在 src/main.tsx 里引入（Ant Design v5 不需要手动引入 CSS，会自动按需加载）：

tsx 复制代码

import React from 'react';
import ReactDOM from 'react-dom/client';
import { ConfigProvider } from 'antd';
import App from './app';
import './styles/global.less';

ReactDOM.createRoot(document.getElementById('root')!).render(
  <ConfigProvider
    theme={{
      token: {
        colorPrimary: '#1677ff',
        borderRadius: 8,
      },
    }}
  >
    <App />
  </ConfigProvider>
);

💡 小贴士 ：ConfigProvider 是 Ant Design 的主题配置入口，可以在这里配置全局主题色、圆角、字号等。

3.5 代码规范：ESLint + Prettier

为什么需要代码规范？

想象一下团队协作的场景：

A 喜欢用双引号，B 喜欢用单引号
A 写分号，B 不写分号
A 缩进 2 空格，B 缩进 4 空格

结果就是代码风格乱七八糟，看别人的代码像看外星文。

ESLint + Prettier 就是来解决这个问题的：

Prettier：管格式（缩进、引号、换行...）
ESLint：管代码质量（有没有 bug、变量用没用到...）

安装

bash 复制代码

npm install eslint prettier eslint-plugin-react eslint-plugin-react-hooks typescript-eslint -D
# 或者
yarn add eslint prettier eslint-plugin-react eslint-plugin-react-hooks typescript-eslint -D

Prettier 配置

创建 .prettierrc.js：

js 复制代码

/** @type {import('prettier').Config} */
export default {
  semi: true,           // 行尾加分号
  singleQuote: true,    // 用单引号
  tabWidth: 2,          // 缩进 2 空格
  trailingComma: 'all', // 末尾加逗号
  printWidth: 100,      // 一行最多 100 个字符
  arrowParens: 'always', // 箭头函数参数加括号
};

ESLint 配置

创建 eslint.config.ts：

typescript 复制代码

import tseslint from 'typescript-eslint';
import react from 'eslint-plugin-react';
import reactHooks from 'eslint-plugin-react-hooks';
import prettier from 'eslint-config-prettier';

export default tseslint.config(
  { ignores: ['dist', 'node_modules'] },
  {
    files: ['**/*.{ts,tsx}'],
    plugins: {
      react,
      'react-hooks': reactHooks,
    },
    rules: {
      ...reactHooks.configs.recommended.rules,
      'react/react-in-jsx-scope': 'off', // React 17+ 不需要 import React
    },
    settings: {
      react: { version: 'detect' },
    },
  },
  prettier // 放在最后，关掉和 Prettier 冲突的规则
);

添加脚本

在 package.json 里加几个方便的命令：

json 复制代码

{
  "scripts": {
    "lint": "eslint --ext .ts,.tsx src",
    "lint:fix": "eslint --ext .ts,.tsx src --fix",
    "format": "prettier --write ."
  }
}

用法：

bash 复制代码

npm run lint      # 检查代码
npm run lint:fix  # 自动修复能修的
npm run format    # 格式化所有文件

3.6 安装路由

安装 react-router-dom：

bash 复制代码

npm install react-router-dom
# 或者
yarn add react-router-dom

创建基础路由结构 src/app.tsx：

tsx 复制代码

import { Navigate, RouterProvider, createBrowserRouter } from 'react-router-dom';
import React from 'react';
import WorkbenchPage from '@/pages/workbench';

const router = createBrowserRouter([
  {
    path: '/',
    element: <Navigate to="/agent/" replace />,
  },
  {
    path: '/agent/',
    element: <WorkbenchPage />,
  },
  {
    path: '/agent/:agentId/',
    element: <WorkbenchPage />,
  },
  {
    path: '/agent/:agentId/:conversationId',
    element: <WorkbenchPage />,
  },
]);

export default function App() {
  return <RouterProvider router={router} />;
}

创建工作台页面 src/pages/workbench/index.tsx：

tsx 复制代码

import React from 'react';
import styles from './index.less';

export default function WorkbenchPage() {
  return (
    <div className={styles.workbench}>
      <h1>AI Agent 工作台</h1>
      <p>欢迎来到你的 AI 助手工作台！</p>
    </div>
  );
}

创建对应的样式文件 src/pages/workbench/index.less：

less 复制代码

.workbench {
  min-height: 100vh;
  padding: @spacing-lg;
  background: @bg-body;
}

3.7 目录结构完善

到这里，你的项目目录大概长这样：

bash 复制代码

ai-agent-workbench/
├── src/
│   ├── app.tsx                    # 路由入口
│   ├── main.tsx                   # 渲染入口
│   ├── pages/
│   │   └── workbench/
│   │       ├── index.tsx          # 工作台页面
│   │       └── index.less         # 工作台样式
│   ├── styles/
│   │   ├── global.less            # 全局样式
│   │   ├── variables.less         # 样式变量
│   │   └── mixins.less            # 样式 mixin
│   ├── components/                # 通用组件（后面会加）
│   └── utils/                     # 工具函数（后面会加）
├── .prettierrc.js                 # Prettier 配置
├── eslint.config.ts               # ESLint 配置
├── vite.config.ts                 # Vite 配置
├── tsconfig.json                  # TypeScript 配置
└── package.json

3.8 本章小结

你学到了什么？

✅ 配置了路径别名（@ 代表 src）
✅ 学会了 Less 和全局样式变量
✅ 安装并配置了 Ant Design
✅ 配置了 ESLint + Prettier 代码规范
✅ 安装了 react-router-dom 并搭建了基础路由
✅ 完善了项目目录结构

小技巧总结

技巧	作用
路径别名 `@`	告别 `../../../../`
样式变量	改主题只改一个变量
Prettier	自动格式化，不用纠结格式
ESLint	提前发现代码问题

✏️ 动手练习

跟着本章步骤，把项目的工程化配置都搭好
新建一个 src/components/Hello.tsx 组件，在工作台页面用 @/components/Hello 的方式引入它
试试运行 npm run lint 和 npm run format，看看有没有报错
试着改一下 variables.less 里的 @primary-color，看看页面会不会变化

下一章是重点！我们会学习 MobX 状态管理------这是整个项目数据流动的核心。

第 3 章 工程化与项目初始化

3.1 什么是「工程化」？

先想一个问题

3.2 路径别名：让导入变优雅

为什么需要路径别名？

怎么配置？

第一步：配置 Vite

第二步：配置 TypeScript

3.3 Less + 全局样式变量

为什么用 Less？

安装 Less

配置全局注入

创建全局样式文件

3.4 安装 Ant Design

3.5 代码规范：ESLint + Prettier

为什么需要代码规范？

安装

Prettier 配置

ESLint 配置

添加脚本

3.6 安装路由

3.7 目录结构完善

3.8 本章小结

你学到了什么？

小技巧总结

✏️ 动手练习

第 3 章工程化与项目初始化