1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

# 第一步：使用 Vite 创建项目
# npm create vite@latest：调用 npm 执行 create-vite 包，@latest 表示用最新版本
# my-app：项目名称（可以改成你喜欢的任意名字）
# -- --template react：这里用了两个短横线（--），各有不同含义：
#   第一个 --（create 前）：是 npm create 的标准分隔符，告诉 npm "后面的都是参数"
#   第二个 --（template 前）：是 create-vite 自己的参数分隔符，表示"接下来是 create-vite 的选项"
#   --template react：指定使用 React 模板（不写这部分会进入交互式菜单，让你手动选择框架）
npm create vite@latest my-app -- --template react

# 运行后会看到类似这样的输出：
# ? Select a framework: react
# ? Select a variant: react
# Scaffolding project in ./my-app...
# Done! Now run:
#   cd my-app
#   npm install
#   npm run dev

# 第二步：进入项目目录
cd my-app

# 第三步：安装依赖（npm 会根据 package.json 自动下载所有需要的包）
npm install
# 打印结果示例：
# added 125 packages in 8s   （安装完成，总共 125 个包）

# 第四步：启动开发服务器！
npm run dev
# 打印结果示例：
#   VITE v5.0.0  ready in 320 ms
#
#   ➜  Local:   http://localhost:5173/
#   ➜  Network: use --host to expose
#   ➜  press h + enter to show help

1

npm run dev

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40

// src/App.jsx
// 第一行：引入 React（React 17 之后，在 JSX 文件里其实可以省略这行，但保留它是好习惯）
import { useState } from 'react'
import reactLogo from './assets/react.svg'  // 引入图片资源
import './App.css'                           // 引入样式文件
import viteLogo from '/vite.svg'            // 引入 public 目录下的静态资源

// 第二步：定义 App 函数组件
function App() {
  // useState 是 React 的 Hook，用来创建"状态"
  // count 是状态的值，setCount 是用来修改状态的方法
  const [count, setCount] = useState(0)

  // 第三步：返回 JSX——这就是组件的"样子"
  return (
    <div className="App">
      {/* JSX 注释这样写 */}
      <header className="App-header">
        {/* img 标签：显示 React logo */}
        <img src={reactLogo} className="App-logo" alt="react logo" />
        {/* p 标签：显示计数 */}
        <p>
          Hello Vite + React!
        </p>
        {/* p 标签：显示当前 count 的值 */}
        <p>
          <button onClick={() => setCount((count) => count + 1)}>
            count is: {count}
          </button>
        </p>
        <p>
          Edit <code>src/App.jsx</code> and save to test HMR
        </p>
      </header>
    </div>
  )
}

// 第四步：导出组件，让其他文件可以引入它
export default App

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "name": "my-app",              // 项目名称
  "private": true,               // 私有项目（防止意外 npm publish）
  "version": "0.0.0",            // 项目版本号（语义化版本：主版本.次版本.修订号）
  "type": "module",              // ES 模块化项目（重要！ESM 模式下 .js 文件被认为是 ES 模块）
  "scripts": {                   // 脚本命令（核心！）
    "dev": "vite",              // npm run dev -> 启动开发服务器
    "build": "vite build",      // npm run build -> 构建生产版本
    "lint": "eslint .",         // npm run lint -> 代码检查
    "preview": "vite preview"    // npm run preview -> 预览生产构建结果
  },
  "dependencies": {              // 生产依赖（项目运行时需要）
    "react": "^19.0.0",         // React 核心库（React 19！）
    "react-dom": "^19.0.0"      // React DOM 渲染库
  },
  "devDependencies": {           // 开发依赖（仅开发时需要）
    "@types/react": "^19.0.0", // React 的 TypeScript 类型定义
    "@types/react-dom": "^19.0.0",  // React DOM 的类型定义
    "@vitejs/plugin-react": "^4.2.1", // Vite 的 React 插件
    "eslint": "^8.55.0",        // 代码检查工具
    "eslint-plugin-react": "^7.33.2",  // ESLint 的 React 插件
    "eslint-plugin-react-hooks": "^4.6.0",  // 检查 React Hooks 规则的插件
    "eslint-plugin-react-refresh": "^0.4.5",  // 检查 HMR 安全性的插件
    "vite": "^5.0.8"           // Vite 构建工具
  }
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

// vite.config.js
import { defineConfig } from 'vite'        // Vite 提供的配置函数
import react from '@vitejs/plugin-react'   // Vite 的 React 插件（支持 JSX、Fast Refresh）

// defineConfig 是一个智能提示工具，让你的配置有类型检查和自动补全
export default defineConfig({
  // plugins 是最重要的配置项
  // react() 插件让 Vite 能够处理 JSX 文件，并启用 Fast Refresh（类比 HMR）
  plugins: [react()],

  // server 是开发服务器的配置
  server: {
    port: 5173,              // 开发服务器端口（默认 5173）
    host: false,            // 是否监听所有网卡（true = 可以用手机访问）
    open: true,             // 启动时自动打开浏览器
    proxy: {                // 代理配置（解决跨域问题）
      '/api': {
        target: 'http://localhost:3000',  // 真实 API 地址
        changeOrigin: true,  // 修改 Origin 头（防止代理失效）
      }
    }
  },

  // build 是生产构建的配置
  build: {
    outDir: 'dist',         // 构建输出目录（默认 dist）
    sourcemap: true,        // 生成 source map（方便生产环境调试）
    chunkSizeWarningLimit: 500,  // 超过 500KB 时警告（单位：KB）
  },

  // resolve 是模块解析的配置
  resolve: {
    alias: {                // 路径别名（简化 import 路径）
      '@': '/src',         // src 目录的简写
    }
  }
})

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

<!DOCTYPE html>
<html lang="zh-CN">
  <head>
    <meta charset="UTF-8" />
    <!-- charset：字符编码，UTF-8 支持几乎所有文字 -->
    <link rel="icon" type="image/svg+xml" href="/vite.svg" />
    <!-- favicon：浏览器标签页上的小图标 -->

    <!-- viewport：移动端适配的关键配置！ -->
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <!--
      width=device-width  -> 让页面宽度等于设备宽度
      initial-scale=1.0   -> 初始缩放比例为 100%
      没有这行代码，移动端的页面会被缩得很小很丑！
    -->

    <title>Vite + React</title>
    <!-- title：浏览器标签页上显示的文字，也是搜索引擎的标题 -->
  </head>
  <body>
    <!-- id="root" 是 React 应用的挂载点 -->
    <!-- React 会把所有组件渲染在这个 div 内部 -->
    <div id="root"></div>

    <!-- 这行 script 标签引入了 React 应用的入口文件 main.jsx -->
    <!-- type="module" 表示这是一个 ES Module，可以写 import/export -->
    <script type="module" src="/src/main.jsx"></script>
  </body>
</html>

1
2
3

# .env.local（不会被提交到 Git，适合放敏感信息）
VITE_API_BASE_URL=https://api.example.com
VITE_API_KEY=sk-1234567890abcdef

1
2
3
4

// 在 React 代码里读取环境变量
// 必须是 VITE_ 开头的变量才能被前端访问到！
const apiBaseUrl = import.meta.env.VITE_API_BASE_URL
console.log(apiBaseUrl)  // 打印结果：https://api.example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

// .eslintrc.cjs
module.exports = {
  root: true,                    // 声明这是 ESLint 的根配置文件，找到此文件后不再向上查找
                               // 如果不写 root: true，ESLint 会继续往上级目录找 .eslintrc 文件
                               // 建议所有项目都加上，避免 eslint 配置"污染"或被覆盖
  env: {
    browser: true,              // 浏览器环境（有 window、document 等全局对象）
    es2021: true,               // ES2021 环境
  },
  extends: [
    // 使用 React 推荐的 ESLint 配置（自动启用 React Hooks 规则）
    'eslint:recommended',
    'plugin:react/recommended',
    'plugin:react/jsx-runtime', // 使用新的 JSX 转换器（不需要每个文件手动 import React）
    'plugin:react-hooks/recommended',  // React Hooks 规则
  ],
  parserOptions: {
    ecmaVersion: 'latest',      // 支持最新版本的 ECMAScript
    sourceType: 'module',       // 使用 ES Module
  },
  settings: {
    react: {
      version: '19.0',          // 告诉 ESLint 你的 React 版本
    },
  },
  // 一些自定义规则覆盖
  rules: {
    'react/react-in-jsx-scope': 'off',  // 关闭"必须在 JSX 文件里 import React"规则（React 17 新语法）
    'react/prop-types': 'off',         // 关闭 PropTypes 运行时类型检查
                                       // PropTypes 是 React 官方提供的运行时类型检查库（如 PropTypes.string）
                                       // 如果你使用 TypeScript（编译时类型检查），则不需要 PropTypes，可以关闭此规则
                                       // 如果你既不用 TypeScript 也不用 PropTypes，则应将此规则设为 'error'
    'react/jsx-uses-react': 'off',    // 关闭 React 未使用的检查（React 17+ 新语法）
  },
}

1
2
3
4
5

// components/index.js
// 统一导出所有组件，这样引入时一行搞定
export { default as Button } from './Button/Button'
export { default as Modal } from './Modal/Modal'
export { default as Card } from './Card/Card'

1
2

// 使用方式（清爽！）
import { Button, Modal, Card } from '@/components'

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

// hooks/useLocalStorage.js
// 自定义 Hook：用 useState 的方式操作 localStorage
import { useState } from 'react'

function useLocalStorage(key, initialValue) {
  // 初次加载时，从 localStorage 读取值
  const [storedValue, setStoredValue] = useState(() => {
    try {
      const item = window.localStorage.getItem(key)
      return item ? JSON.parse(item) : initialValue
    } catch (error) {
      return initialValue
    }
  })

  // 写入时，同步更新 state 和 localStorage
  const setValue = (value) => {
    try {
      const valueToStore = value instanceof Function ? value(storedValue) : value
      setStoredValue(valueToStore)
      window.localStorage.setItem(key, JSON.stringify(valueToStore))
    } catch (error) {
      console.error('localStorage 写入失败:', error)
    }
  }

  return [storedValue, setValue]
}

export default useLocalStorage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

// utils/formatDate.js
/**
 * 格式化日期
 * @param {Date|string|number} date - 日期
 * @param {string} format - 格式字符串，如 'YYYY-MM-DD HH:mm:ss'
 * @returns {string} 格式化后的日期字符串
 */
export function formatDate(date, format = 'YYYY-MM-DD') {
  const d = new Date(date)
  const year = d.getFullYear()
  const month = String(d.getMonth() + 1).padStart(2, '0')
  const day = String(d.getDate()).padStart(2, '0')
  const hours = String(d.getHours()).padStart(2, '0')
  const minutes = String(d.getMinutes()).padStart(2, '0')
  const seconds = String(d.getSeconds()).padStart(2, '0')

  return format
    .replace('YYYY', year)
    .replace('MM', month)
    .replace('DD', day)
    .replace('HH', hours)
    .replace('mm', minutes)
    .replace('ss', seconds)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43

// api/request.js
import axios from 'axios'

// 创建 axios 实例
const request = axios.create({
  baseURL: import.meta.env.VITE_API_BASE_URL,  // API 基础地址
  timeout: 10000,        // 请求超时 10 秒
  headers: {
    'Content-Type': 'application/json',
  },
})

// 请求拦截器：在请求发送之前做一些处理
request.interceptors.request.use(
  (config) => {
    // 比如在这里添加 token
    const token = localStorage.getItem('token')
    if (token) {
      config.headers.Authorization = `Bearer ${token}`
    }
    return config
  },
  (error) => {
    return Promise.reject(error)
  }
)

// 响应拦截器：在响应回来之后做一些处理
request.interceptors.response.use(
  (response) => {
    // 如果响应的状态码是 2xx，直接返回数据
    return response.data
  },
  (error) => {
    // 如果是 401（未授权），跳转到登录页
    if (error.response?.status === 401) {
      window.location.href = '/login'
    }
    return Promise.reject(error)
  }
)

export default request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

// api/products.js
import request from './request'

// 获取产品列表
export function getProducts(params) {
  return request.get('/products', { params })
}

// 获取单个产品详情
export function getProductById(id) {
  return request.get(`/products/${id}`)
}

// 创建新产品
export function createProduct(data) {
  return request.post('/products', data)
}

// 更新产品
export function updateProduct(id, data) {
  return request.put(`/products/${id}`, data)
}

// 删除产品
export function deleteProduct(id) {
  return request.delete(`/products/${id}`)
}

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// stores/authStore.js
// 使用 Zustand 进行状态管理（比 Redux 简洁得多！）
import { create } from 'zustand'

const useAuthStore = create((set) => ({
  // 状态
  user: null,       // 用户信息
  token: null,      // 登录 token
  isAuthenticated: false,  // 是否已登录

  // 方法（更新状态）
  login: (user, token) => set({
    user,
    token,
    isAuthenticated: true
  }),

  logout: () => set({
    user: null,
    token: null,
    isAuthenticated: false
  }),

  updateUser: (updates) => set((state) => ({
    user: { ...state.user, ...updates }
  })),
}))

export default useAuthStore

1
2
3
4
5

// public 目录的文件，引用方式：
// 假设 public/robots.txt 存在
// 在代码里这样引用：
const robotsUrl = '/robots.txt'
console.log(robotsUrl)  // 打印结果：/robots.txt

1
2
3
4
5
6
7

// src/assets/ 的文件，引用方式：
import logo from '@/assets/logo.png'
// 或者
import logo from './assets/logo.png'

// 在 JSX 里使用：
<img src={logo} alt="logo" />