# 检查 Node.js 是否已安装及当前版本
node -v
# 期望输出示例：v18.17.0

# 检查 npm 版本（npm 随 Node.js 一起安装）
npm -v
# 期望输出示例：9.6.7

# 使用 nvm 安装 Node.js LTS 版本
nvm install 20
nvm use 20

node  -v    # 检查 Node.js 版本
npm   -v    # 检查 npm 版本
npx   -v    # npx 用于执行本地或临时安装的包（npm ≥ 5.2.0 自带）

# 在目标目录下执行，my-app 为项目名称（可按需修改）
npx create-react-app my-app

# 1. 进入项目目录
cd my-app

# 2. 启动开发服务器
npm start

# 确认项目目录中存在关键文件
ls src/App.js   # Windows 下用 dir src\App.js
ls public/index.html
ls package.json

# 运行打包命令验证项目完整性
npm run build
# 成功后在 build/ 目录下生成静态资源

my-app/
├── node_modules/              # 依赖包目录
├── public/                    # 静态资源目录
│   ├── index.html             # 应用唯一 HTML 页面（模板文件）
│   ├── favicon.ico            # 网站图标
│   ├── logo192.png            # PWA 用 192×192 应用图标
│   ├── logo512.png            # PWA 用 512×512 应用图标
│   ├── manifest.json          # PWA 清单文件（定义应用名称、图标等）
│   └── robots.txt             # 搜索引擎爬虫规则文件
├── src/                       # 应用源代码目录（核心开发区域）
│   ├── App.css                # App 组件的样式文件
│   ├── App.js                 # 根组件（应用的主组件）
│   ├── App.test.js            # App 组件的单元测试文件
│   ├── index.css              # 全局样式文件
│   ├── index.js               # 应用入口文件（挂载 React 到 DOM）
│   ├── logo.svg               # React Logo 的 SVG 资源
│   ├── reportWebVitals.js     # Web 性能指标上报工具
│   └── setupTests.js          # 测试框架初始化配置
├── .gitignore                 # Git 忽略规则
├── package.json               # 项目清单与依赖声明（核心配置文件）
├── package-lock.json          # 依赖版本锁定文件
└── README.md                  # 项目说明文档

{
  // ==================== 项目标识信息 ====================

  "name": "my-app",
  // 项目名称。发布到 npm registry 时用作包名，必须为小写、URL 友好、唯一

  "version": "0.1.0",
  // 项目当前版本号，遵循语义化版本（SemVer）规范：主版本.次版本.修订号
  // 初始为 0.1.0，表示处于早期开发阶段

  "private": true,
  // 标记为私有项目，防止意外发布到 npm registry。
  // 项目模板默认设为 true，实际生产项目建议也保持为 true
  // 若设为 false 且执行 npm publish，会将整个项目发布到公共 npm 仓库

  // ==================== 依赖声明 ====================

  "dependencies": {
    // 生产依赖：项目运行时必须的第三方包，打包后会被包含在最终产物中
    "@testing-library/jest-dom": "^5.17.0",
    // DOM 断言库扩展（配合 Jest 使用），如 .toBeInTheDocument() 等语义化匹配器

    "@testing-library/react": "^13.4.0",
    // React 测试工具库，提供 render()、screen 等 API，模拟用户在浏览器中的操作行为

    "@testing-library/user-event": "^13.5.0",
    // 模拟用户交互事件（点击、输入、选择等），比 fireEvent 更贴近真实用户行为

    "react": "^18.2.0",
    // React 核心库，提供组件、Hooks、虚拟 DOM、Fiber 调度等核心能力

    "react-dom": "^18.2.0",
    // React 的 DOM 渲染器，负责将 React 虚拟 DOM 渲染为真实浏览器 DOM，
    // 提供 createRoot、render、hydrate 等 DOM 相关 API

    "react-scripts": "5.0.1",
    // CRA 的核心工程化封装包，内部集成了 Webpack、Babel、ESLint、Jest 等全套配置。
    // 开发者的项目无需暴露底层配置，开箱即用

    "web-vitals": "^2.1.4",
    // Google 提出的 Web 性能指标库，用于测量 CLS、FID、FCP、LCP、TTFB 等核心指标
  },

  // ==================== 脚本命令 ====================

  "scripts": {
    // npm scripts：定义项目中可通过 npm run <script-name> 执行的命令

    "start": "react-scripts start",
    // 启动开发服务器（默认监听 http://localhost:3000）
    // 支持热模块替换（HMR）：修改代码后浏览器自动更新，无需手动刷新
    // 开发模式下代码未压缩，便于调试

    "build": "react-scripts build",
    // 生产环境打包构建，在 build/ 目录输出优化后的静态资源
    // 会对 JS/CSS/HTML 进行压缩、混淆、Tree Shaking、代码分割等优化

    "test": "react-scripts test",
    // 以交互式监听模式启动 Jest 测试运行器
    // 默认查找 src/ 下 *.test.js 和 *.spec.js 文件

    "eject": "react-scripts eject",
    // 将 CRA 封装的所有底层配置（Webpack、Babel、ESLint 等）暴露到项目根目录。
    // 此操作不可逆！执行后项目将脱离 CRA 的封装管理，适合需要深度自定义构建配置的场景。
    // 绝大多数项目不需要执行此命令
  },

  // ==================== ESLint 配置 ====================

  "eslintConfig": {
    // ESLint 代码检查规则配置（CRA 内置，无需额外安装 ESLint）
    "extends": [
      "react-app", // CRA 定制的 ESLint 规则集，包含 React 最佳实践
      "react-app/jest", // Jest 测试文件的 ESLint 规则集
    ],
  },

  // ==================== 浏览器兼容性配置 ====================

  "browserslist": {
    // 声明项目需要支持的浏览器范围，由 Babel、Autoprefixer、PostCSS 等工具共用
    "production": [
      // 生产环境的浏览器目标
      ">0.2%", // 全球使用率超过 0.2% 的浏览器
      "not dead", // 排除已停止更新的浏览器（如 IE 11）
      "not op_mini all", // 排除 Opera Mini（其市场份额极小且 JS 支持有限）
    ],
    "development": [
      // 开发环境的浏览器目标（通常宽松配置以提升构建速度）
      "last 1 chrome version", // 最新一个版本的 Chrome
      "last 1 firefox version", // 最新一个版本的 Firefox
      "last 1 safari version", // 最新一个版本的 Safari
    ],
  },

  // ==================== Browserslist 开发依赖（自动生成） ====================

  "devDependencies": {
    // （通常无，CRA 默认不需要额外开发依赖）
    // 如需添加，自行执行 npm install -D <包名> 并在此处出现
  },
}

// package.json 中声明（允许浮动）
"react": "^18.2.0"

// package-lock.json 中锁定（精确到具体版本）
"node_modules/react": {
  "version": "18.2.0",
  "resolved": "https://registry.npmjs.org/react/-/react-18.2.0.tgz",
  "integrity": "sha512-..."
}

// 某包及其所有子依赖的完整信息
"node_modules/postcss": {
  "version": "8.4.31",
  "dependencies": {
    "nanoid": "^3.3.6",
    "picocolors": "^1.0.0",
    "source-map-js": "^1.0.2"
  }
}

# CI/CD 或生产环境推荐使用 npm ci 而非 npm install
npm ci
# npm ci 的特点：
#   1. 严格按照 package-lock.json 安装，不更新任何锁定版本
#   2. 安装前自动删除 node_modules，确保干净环境
#   3. 如果 package.json 和 package-lock.json 版本不一致，直接报错退出

# 使用 Vite 官方模板创建 React 项目
npm create vite@latest my-vite-app -- --template react

# 进入项目并安装依赖
cd my-vite-app
npm install

// vite.config.js
import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";
import { fileURLToPath, URL } from "node:url";

export default defineConfig({
  plugins: [react()],

  resolve: {
    alias: {
      // ① @ —— 指向 src 根目录
      "@": fileURLToPath(new URL("./src", import.meta.url)),

      // ② @components —— 指向 src/components 目录
      "@components": fileURLToPath(
        new URL("./src/components", import.meta.url),
      ),

      // ③ ~img —— 指向 src/assets/images 目录
      "~img": fileURLToPath(new URL("./src/assets/images", import.meta.url)),

      // ④ #types —— 指向 src/types 目录
      "#types": fileURLToPath(new URL("./src/types", import.meta.url)),
    },
  },
});

// ❌ 传统相对路径写法（层级深时难以维护）
import Header from "../../components/Header";
import Logo from "../../assets/images/logo.png";
import { UserInfo } from "../../types/user";

// ✅ 路径别名写法（简洁、可读、易重构）
import Header from "@components/Header";
import Logo from "~img/logo.png";
import { UserInfo } from "#types/user";

// jsconfig.json（放置在项目根目录）
{
  "compilerOptions": {
    // 项目基础目录（即 jsconfig.json 所在目录）
    "baseUrl": ".",

    // 路径映射：将别名映射到实际文件系统路径
    "paths": {
      "@/*": ["./src/*"], // @/components/Header → src/components/Header
      "@components/*": ["./src/components/*"], // @components/Header  → src/components/Header
      "~img/*": ["./src/assets/images/*"], // ~img/logo.png      → src/assets/images/logo.png
      "#types/*": ["./src/types/*"], // #types/user         → src/types/user.ts
    },
  },

  // 告知 VS Code 哪些目录属于项目范围（提升搜索准确性和性能）
  "include": ["src"],

  // 排除不需要编辑器索引的目录
  "exclude": ["node_modules", "dist", "build"],
}

// tsconfig.json（在 Vite 模板默认配置基础上追加）
{
  "compilerOptions": {
    // ... Vite 生成的默认配置 ...

    // --- 追加以下字段实现路径别名 ---
    "baseUrl": ".",
    "paths": {
      "@/*": ["./src/*"],
      "@components/*": ["./src/components/*"],
      "~img/*": ["./src/assets/images/*"],
      "#types/*": ["./src/types/*"],
    },
  },
  "include": ["src"],
  // 确保 vite.config.ts 中的 paths 引用正确：
  // 若 tsconfig.json 的 baseUrl 为 ".", 而 vite.config.ts 中
  // 使用了 path.resolve(__dirname, './src'), 则两者保持一致即可
}

# 启动 Vite 开发服务器验证
npm run dev