一个使用 Antd 的 react 模板

笔记中使用 Node 版本为 22.21.1

使用 Vite 作为构建工具. 基本步骤:

  1. 安装包与依赖
  2. 配置路径别名 @
  3. 配置 vscode 折叠
  4. 配置环境 .env
  5. 配置路由表
npm create vite@latest

npm i http-server -D
npm i tailwindcss @tailwindcss/vite
npm i sass -D
npm i classnames -S

npm i vitest -D

npm i debug -S
npm i @types/debug -D

npm i lodash-es -S
npm i @types/lodash-es -D

npm i mockjs -S
npm i @types/mockjs -D

npm i axios -S

npm i antd -S
npm i @ant-design/icons@6.x -S
npm i dayjs -S

npm i react-router -S

1. 新建项目并整理代码文件

创建项目的命令

npm create vite@latest

然后脚手架会先后提示

  1. 项目名称 (Project name)
  2. 使用什么模板 (Select a framework): React
  3. 使用什么架构 (主要是 TS 等): TypeScript + React Compiler
  4. 然后询问是否使用 rolldown-vite
  5. 最后是询问是否安装依赖包, 并运行.

image-20251222144621742

最后项目就可以跑起来了.

清理一下代码结构, src 下仅保留 src/main.tsx, 这是组件的入口. 以及 App.tsx, 这个是渲染的第一个组件. 根据需要可以将其替换.

image-20251222145501422

// main.tsx
import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import App from './App.tsx'

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
)

// App.tsx
const App = () => <h1>Hello React</h1>
export default App

image-20251222145704742

1.1 配置路径别名

在 tsconfig.app.json 中添加路径别名, 以及基路径:

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

在 vite.config.ts 中导入 fileURLToPath, 添加路径别名配置:

import { fileURLToPath } from 'node:url'

export default defineConfig({
  resolve: {
    alias: {
      '@': fileURLToPath(new URL('./src', import.meta.url))
    }
  }
})

2. 调整代码结构(vsCode 配置)

基本步骤:

  1. 新建 .vscode 目录, 创建 settings.json 文件, 添加折叠代码配置
  2. 分别创建 .env, .env.development, 以及 .env.production 文件, 对开发环境与生成环境分别进行配置.
  3. 修改 package.json 的 scripts 节点, 在运行命令后添加 --mode development 或 --mode production 来区别配置.
  4. 在 src 目录中添加 vite-env.d.ts 来定义配置数据的类型. 详细配置可以参考文档.
// .vscode/settings.json 的配置
{
  "explorer.fileNesting.enabled": true,
  "explorer.fileNesting.patterns": {
    "*.ts": "${capture}.js",
    "*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts",
    "*.jsx": "${capture}.js",
    "*.tsx": "${capture}.ts",
    "tsconfig.json": "tsconfig.*.json",
    "package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, bun.lock",
    ".env": ".env.*",
  }
}

image-20251222150654523

类型定义

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

interface ViteTypeOptions {
  // 添加这行代码，你就可以将 ImportMetaEnv 的类型设为严格模式，
  // 这样就不允许有未知的键值了。
  // strictImportMetaEnv: unknown
}

interface ImportMetaEnv {
  /** 运行环境名 */
  readonly VITE_MODE: string
  // 更多环境变量...
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

image-20251222151022730

"scripts": {
  "dev": "vite --mode development",
  "build": "tsc -b && vite build --mode production",
},

在 main.tsx 执行打印环境信息: console.log(环境: %s, import.meta.env.VITE_MODE)

image-20251222151247588

安装 http-server, 然后构建后, 进入 dist 目录, 再部署一次静态文件查看:

npm i http-server -D
npm run build
cd dist
npx http-server -o

image-20251222151606741

运行的结果为

image-20251222151645171

必要时修改 vite.config.ts 文件, 启用自定义的 IP 与端口号:

export default defineConfig({
  server: {
    host: true,
    port: 3000,
  }
})

image-20251222151911190

3. 安装样式工具

推荐使用 tailwind CSS, 必要是使用 Sass 来补充. 依次安装:

npm i tailwindcss @tailwindcss/vite
npm i sass -D
npm i classnames -S

修改 vite.config.ts, 导入 tailwindcss 插件并配置:

import tailwindcss from '@tailwindcss/vite'

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

然后在全局 css 文件中导入即可. 可以在 main.tsx 所在目录创建 index.css 文件, 并填入:

@import "tailwindcss";

然后在 main.tsx 中导入即可:

import './index.css'

然后在页面中可以立即演示:

image-20251222153012200

image-20251222153033203

3.1 使用 sass 与 classnames

样式使用模块化的方式编码.

  1. 创建 module.scss 后缀的样式文件名. 编写 scss 代码.
  2. 使用 classnames 的绑定模式, 加载样式.

image-20251222155340830

image-20251222155426637

运行结果为:

image-20251222155440199

4. 安装其他工具

npm i vitest -D # 用于单元测试

npm i debug # 用于打印日志
npm i @types/debug -D

npm i lodash-es # 辅助工具方法
npm i @types/lodash-es -D

npm i mockjs # 模拟数据
npm i @types/mockjs -D

npm i axios # 请求

5. 安装 antd

antd 默认就支持按需加载.

  1. 安装 antd 与 @ant-design/icons@6.x 安装必要的组件.
  2. 安装 dayjs 来配置时间工具.
  3. 配置 ConfigProvider.
npm i antd -S
npm i @ant-design/icons@6.x -S
npm i dayjs -S

然后修改入口文件 main.tsx

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ConfigProvider } from 'antd'
import zhCN from 'antd/locale/zh_CN'
import App from './App.tsx'
import './index.css'

import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh-cn')

console.log(`环境: %s`, import.meta.env.VITE_MODE)

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfigProvider locale={zhCN}>
      <App />
    </ConfigProvider>
  </StrictMode>,
)

然后就可以在需要的组件中, 导入并使用了.

import ClassName from 'classnames/bind'
import styles from './App.module.scss'
import { Button, message, Space } from 'antd'
const cx = ClassName.bind(styles)

const testClickHandler = () => {
  message.info('一段测试')
}

const App = () => <>
  <h1 className="text-2xl font-bold text-red-500">Hello React</h1>
  <h2 className={cx('jk-container')}>Hello React 2</h2>
  
  <div className="my-4">
    <Space>
      <Button onClick={testClickHandler}>默认按钮</Button>
    </Space>
  </div>
</>
export default App

运行结果为:

image-20251222162353585

6. 导入路由

npm i react-router

配置路由:

  1. 在 src 目录下创建 routers 目录, 并创建 index.ts 文件.
  2. 定义路由对象:
    1. 从 react-router 导入 createBrowserRouter.
    2. 调用 createBrowserRouter 配置路由表, 并导出结果.
    3. 将原有的 App 组件移除, 定义成其他组件, 创建文件夹 views, 集中放置页面组件.
    4. 将原有 App 组件定义到路由表中.
  3. 重写入口模块 main.tsx
    1. 从 antd 导入 App 组件.
    2. 从 react-router 中导入 RouterProvider 组件.
    3. 导入路由表.

定义路由表:

// 将原有 App.tsx 重新命名为 TestPage, 然后放在 `@/views` 目录中
import { lazy } from 'react'
import { createBrowserRouter } from 'react-router'

export default createBrowserRouter([
  {
    path: '/test-page',
    Component: lazy(() => import('@/views/TestPage/TestPage'))
  },
])

修改入口文件:

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import { ConfigProvider, App } from 'antd'
import { RouterProvider } from 'react-router'
import router from '@/routers'
import zhCN from 'antd/locale/zh_CN'
import './index.css'

import dayjs from 'dayjs'
import 'dayjs/locale/zh-cn'
dayjs.locale('zh-cn')

console.log(`环境: %s`, import.meta.env.VITE_MODE)

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <ConfigProvider locale={zhCN}>
      <App>
        <RouterProvider router={router} />
      </App>
    </ConfigProvider>
  </StrictMode>,
)

单纯从运行上没有区别, 但是注意路由表 test-page, 如果按照以前的访问:

image-20251222164624254

修改地址后:

image-20251222164647500

至此基本工具已配置完成.

Last Updated:
Contributors: jk