项目前置准备

本文档为 React 极客园后台项目上手的“快速指南”。

目标读者：已具备基本 JavaScript/React 知识，希望快速搭建一个项目脚手架并在团队中可复用。

你将学到

• 选择与初始化项目的推荐方式（Vite/Cra）
• 项目目录与文件约定
• 使用 Sass（SCSS）进行样式预处理的规范
• 集成组件库（Ant Design）及最佳实践
• 配置路由（react-router-dom）与代码示例
• 路径别名配置（IDE 与构建工具）
• Git 版本控制与代码规范建议

---

快速开始（推荐：Vite + React）

# 使用 Yarn（或 npm）创建 Vite + React 项目
npm create vite@latest my-react-app -- --template react
cd my-react-app
npm install
npm run dev

访问 http://localhost:5173 验证项目启动。

---

项目目录建议（约定优于配置）

推荐保持一致、可扩展的目录结构：

src/
├─ api/             # 请求封装与接口定义
├─ assets/          # 静态资源（图片、字体）
├─ components/      # 通用可复用组件
├─ pages/           # 路由页面组件
├─ store/           # 全局状态（Redux/Pinia/Context）
├─ hooks/           # 自定义 Hooks
├─ utils/           # 工具函数（axios、token 管理）
├─ App.jsx
└─ main.jsx

推荐在 PR 中加入 README 或 CONTRIBUTING.md，说明目录的目的和放置规则。

---

样式：使用 Sass（SCSS）

为什么用 Sass

• 支持嵌套、变量、混合（mixins）和模块化
• 与现代构建工具（Vite）直接兼容，使用体验良好

安装与全局约定

npm install -D sass

在 src/styles/ 下组织样式：

src/styles/
├─ variables.scss
├─ mixins.scss
├─ base.scss       # 全局 reset + 基础样式
└─ index.scss      # 在 main.jsx 中引入

main.jsx 中引入：

import './styles/index.scss'

---

引入reset.scss样式文件

本文件用于重置浏览器的默认样式，保证各浏览器下的表现一致。

• 内容包括：

  1. HTML5 标签统一处理
  2. 常见标签的 margin / padding 重置
  3. 列表、表格、表单等元素的基础样式修复
  4. 提供基础的全局变量（可扩展）

• 使用方法：

在项目的入口文件（如 index.js / main.jsx）中引入：

 import "@/styles/reset.scss";

• reset.scss 文件内容如下：

 /* 1. 全局统一 */
 html, body, div, span, applet, object, iframe,
 h1, h2, h3, h4, h5, h6, p, blockquote, pre,
 a, abbr, acronym, address, big, cite, code,
 del, dfn, em, img, ins, kbd, q, s, samp,
 small, strike, strong, sub, sup, tt, var,
 b, u, i, center,
 dl, dt, dd, ol, ul, li,
 fieldset, form, label, legend,
 table, caption, tbody, tfoot, thead, tr, th, td,
 article, aside, canvas, details, embed, 
 figure, figcaption, footer, header, hgroup, 
 menu, nav, output, ruby, section, summary,
 time, mark, audio, video {
   margin: 0;
   padding: 0;
   border: 0;
   font-size: 100%;
   font: inherit;
   vertical-align: baseline;
 }

 /* 2. HTML5 元素设置为 block */
 article, aside, details, figcaption, figure, 
 footer, header, hgroup, menu, nav, section {
   display: block;
 }

 /* 3. 基础排版 */
 body {
   line-height: 1.5;
   font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, 
     "Helvetica Neue", Arial, "Noto Sans", sans-serif, "Apple Color Emoji", 
     "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji";
   background-color: #f5f6fa;
   color: #333;
 }

 /* 4. 列表 */
 ol, ul {
   list-style: none;
 }

 /* 5. 链接 */
 a {
   text-decoration: none;
   color: inherit;
 }

 /* 6. 表格 */
 table {
   border-collapse: collapse;
   border-spacing: 0;
 }

 /* 7. 表单元素 */
 button, input, select, textarea {
   font: inherit;
   border: none;
   outline: none;
   background: transparent;
 }

 /* 8. 图片 */
 img {
   max-width: 100%;
   height: auto;
   display: block;
 }

 /* 9. 其他常见处理 */
 * {
   box-sizing: border-box;
 }

集成组件库：Ant Design

npm install antd

在按需加载与主题定制方面，建议使用 babel-plugin-import（CRA）或按需引入（Vite + unplugin）以减少包体积。

示例：在 pages/Login.jsx 中测试按钮

import { Button } from 'antd'

export default function Login() {
  return (
    <div>
      <h1>登录</h1>
      <Button type="primary">测试按钮</Button>
    </div>
  )
}

---

路径别名（@ -> src）

Vite：在 vite.config.js 中添加别名：

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') }
  }
})

VSCode 提示：jsconfig.json / tsconfig.json

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

---

路由：react-router-dom（v6+）

npm install react-router-dom

在 router/index.jsx 中配置路由示例：

import { createBrowserRouter } from 'react-router-dom'
import Layout from '@/pages/layout'
import Login from '@/pages/Login'

const router = createBrowserRouter([
  { path: '/', element: <Layout />, children: [ /* 子路由 */ ] },
  { path: '/login', element: <Login /> }
])

export default router

在 main.jsx 中使用：

import { RouterProvider } from 'react-router-dom'
import router from './router'

ReactDOM.createRoot(document.getElementById('root')).render(
  <React.StrictMode>
    <RouterProvider router={router} />
  </React.StrictMode>
)

---

Git 与代码托管

推荐：

• 使用 main 或 master（团队约定）作为保护分支
• 提交规范采用 Conventional Commits 或通过 commitlint 强制
• 使用 CI（GitHub Actions / GitLab CI）做 PR 校验（lint、测试、构建）

常用远程操作：

git remote add origin git@...:repo.git
git push -u origin main

---