Vite React 模板解析：最小化 HMR 脚手架、双官方插件选择与 Oxlint 规则配置

2026-09-04 15:24:31作者：董斯意

本文围绕 Vite 官方脚手架 create-vite 中的 React 模板（packages/create-vite/template-react/）展开，覆盖该模板的完整最小配置、目录与源码结构、@vitejs/plugin-react 与 @vitejs/plugin-react-swc 两种官方插件的选型，以及模板内置 Oxlint 规则的解读与扩展方法。读完本文，你可以直接基于该模板启动一个带 HMR 的 React 开发环境，理解每个配置文件的作用，并知道如何按生产需求扩展 lint 配置或接入 React Compiler。

模板定位：create-vite 中的 React 条目

create-vite 是 Vite 官方提供的项目脚手架，位于 packages/create-vite/，当前版本为 9.2.0（见 packages/create-vite/package.json）。从 packages/create-vite/src/index.ts 的模板定义可以看到，React 家族包含三个内置条目：

react：纯 JavaScript 模板，即本文分析的 template-react/；
react-ts：TypeScript 版本（template-react-ts/）；
react-compiler-ts：预置 React Compiler 的 TypeScript 版本。

选择 react 后执行 npm create vite@latest my-app -- --template react，脚手架会把该模板目录复制到目标项目（模板内以 _gitignore、_oxlintrc.json 命名的文件在落地时会被还原为 .gitignore、.oxlintrc.json），你得到的就是下文逐文件剖析的最小 React + Vite 工程。

最小配置全景：模板文件结构

该模板的设计目标是"以尽可能少的文件让 React 跑起来并支持 HMR"（template-react/README.md）。完整文件结构如下：

template-react/
├── index.html          # 唯一的 HTML 入口
├── package.json        # 依赖与 scripts
├── vite.config.js      # Vite 配置（仅注册 react 插件）
├── _oxlintrc.json      # Oxlint 规则配置
├── public/
│   ├── favicon.svg
│   └── icons.svg       # SVG symbol 图标集
└── src/
    ├── main.jsx        # 挂载入口（StrictMode + createRoot）
    ├── App.jsx         # 演示组件（计数器 + HMR）
    ├── App.css
    ├── index.css
    └── assets/         # hero.png、react.svg、vite.svg

index.html：入口即模块入口点

index.html 是整个应用的 HTML 入口，核心只有两行：

<body>
  <div id="root"></div>
  <script type="module" src="/src/main.jsx"></script>
</body>

<div id="root"> 是 React 的挂载点；type="module" 的 script 标签指向 /src/main.jsx，Vite 在开发模式下会把它当作模块入口直接以原生 ESM 方式交给浏览器，这正是 Vite "dev server 不打包、按需编译"理念的直接体现。

main.jsx 与 App.jsx：StrictMode 与 HMR 验证组件

src/main.jsx 使用 React 18+ 的并发渲染 API 完成挂载：

import { StrictMode } from 'react'
import { createRoot } from 'react-dom/client'
import './index.css'
import App from './App.jsx'

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

src/App.jsx 是一个带 useState 计数器的演示组件，其注释文案明确要求"Edit src/App.jsx and save to test HMR"——它本身就是一份 HMR 验收用例：保存文件后，浏览器中的 count 状态不会丢失，仅组件被热替换。组件内通过 import heroImg from './assets/hero.png' 演示了 Vite 的静态资源导入能力（图片经处理后可像 JS 模块一样导入）。

vite.config.js：只有一个插件

vite.config.js 的全部内容：

import react from '@vitejs/plugin-react'
import { defineConfig } from 'vite'

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

模板刻意保持零额外配置：不写 base、server、build 等任何字段，全部走 Vite 默认值。react() 插件负责 JSX/JSX 的转换与 React 刷新（Fast Refresh）注入，是开发体验的核心。

依赖与脚本：package.json 逐项说明

template-react/package.json 定义了依赖与全部可用的 npm scripts：

依赖	版本	作用
`react` / `react-dom`	`^19.2.8`	React 19 运行时（运行时依赖，打进产物）
`@vitejs/plugin-react`	`^6.1.1`	官方 React 插件，基于 Oxc 做 JSX 转换
`oxlint`	`^1.80.0`	Ox 项目的 Rust 编写 linter，替代 ESLint 承担 lint
`vite`	`^8.2.2`	Vite 8 本体（dev server + 构建器）
`@types/react` / `@types/react-dom`	`^19.2.x`	类型定义（JS 模板中保留，便于随时混用 TS 工具链）

scripts 四件套覆盖了完整工作流：

{
  "dev": "vite",            // 启动 dev server（HMR）
  "build": "vite build",    // 生产构建
  "lint": "oxlint",         // 使用 Oxlint 做静态检查
  "preview": "vite preview" // 本地预览生产产物
}

"type": "module" 声明整个项目使用 ESM，与 Vite 的 ESM 优先设计保持一致。

两个官方 React 插件：Oxc 与 SWC 的选型

template-react/README.md 指出，目前有两个官方插件可选，模板默认使用前者：

@vitejs/plugin-react（模板默认）：底层使用 Oxc 做 JSX 转换，是 Ox 项目生态的一部分，与模板中同样来自 Ox 的 oxlint 形成一致的技术栈；
@vitejs/plugin-react-swc：底层使用 SWC，是更早期、社区使用更广泛的方案。

两者都在 @vitejs/vite-plugin-react 仓库下维护，切换方式是在 package.json 中替换 devDependency，并把 vite.config.js 中的导入从 @vitejs/plugin-react 改为 @vitejs/plugin-react-swc，插件名同样为 react。对大多数项目，默认选择 @vitejs/plugin-react 即可；只有在已有 SWC 相关生态依赖（如 SWC 构建工具链）时，选择 SWC 版本更便于统一心智模型。

为什么模板默认不启用 React Compiler

README 中有一条容易被忽略但重要的决策说明：React Compiler 默认不启用，原因是它对 dev 与 build 的性能有负面影响（引入编译器会显著增加每次转换和构建的耗时）。模板因此保持"开箱即最快"的默认姿态，同时为需要的用户保留了 react-compiler-ts 这个专门的子模板（见 create-vite 模板定义）。

从源码结构看，react-compiler-ts 是 react-ts 的派生条目，说明官方的推荐路径是：React Compiler 是 TypeScript 项目的一个可选增强，而非 JS 模板的默认项。如果你确需启用，按 React 官方的 React Compiler 安装文档操作，或在脚手架时直接选择 react-compiler-ts 模板。

Oxlint 配置：模板内置的两条规则与生产扩展

模板内置的 lint 配置在 _oxlintrc.json（落地项目后为 .oxlintrc.json）：

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["react", "oxc"],
  "rules": {
    "react/rules-of-hooks": "error",
    "react/only-export-components": ["warn", { "allowConstantExport": true }]
  }
}

逐条解读：

plugins: ["react", "oxc"]：启用 React 专属规则集与 Ox 自己的规则集；
react/rules-of-hooks: "error"：Hooks 规则违规直接报错，防止 useEffect 依赖遗漏、条件调用 Hooks 等运行时错误流入产物；
react/only-export-components: ["warn", { "allowConstantExport": true }]：警告"一个模块同时导出组件与非组件"的情况。这种混导出会破坏 Fast Refresh 的局部刷新能力（非组件导出变化会导致整个模块被整体替换而非热替换）。allowConstantExport 选项允许导出常量，避免对纯常量工具模块误报。

这条规则与 HMR 体验直接相关：想让 Fast Refresh 生效，组件模块应保持"只导出组件"的纪律——这正是模板把它设为 warn 级的原因。

生产环境的推荐扩展：TypeScript + 类型感知规则

template-react/README.md 建议：生产应用应使用 TypeScript 并开启类型感知（type-aware）lint 规则，指向 TS 模板。template-react-ts/README.md 给出了具体的扩展方式——安装 oxlint-tsgolint 并编辑 .oxlintrc.json：

{
  "$schema": "./node_modules/oxlint/configuration_schema.json",
  "plugins": ["react", "typescript", "oxc"],
  "options": {
    "typeAware": true
  },
  "rules": {
    "react/rules-of-hooks": "error",
    "react/only-export-components": ["warn", { "allowConstantExport": true }]
  }
}

相对 JS 模板的差异就三处：plugins 增加 "typescript"、新增 options.typeAware: true、保留原有规则。开启后 linter 可以利用类型信息捕获 rules-of-hooks 之外的深层问题（如错误的 props 传递引发的 Hooks 误用），规则全集可参考 Oxlint 的官方 rules 文档（Oxlint 项目官网，仓库 README 中已注明出处）。

上手实操：安装、开发、构建与预览

按模板提供的 scripts，完整流程如下（在项目落地后执行）：

# 1. 用 create-vite 生成项目（选择 react 模板）
npm create vite@latest my-react-app -- --template react
cd my-react-app

# 2. 安装依赖
npm install

# 3. 启动开发服务器（HMR 生效，默认 http://localhost:5173）
npm run dev

# 4. 静态检查（Oxlint）
npm run lint

# 5. 生产构建（输出到 dist/）
npm run build

# 6. 本地预览构建产物
npm run preview

验证 HMR 的官方姿势就是模板注释里写的：编辑 src/App.jsx（例如修改计数器文案），保存后浏览器即时刷新且 count 状态保留，即证明 Fast Refresh 正常工作。

小结与文件索引

template-react 的价值在于"最小但完整"：一个 HTML 入口、一个挂载脚本、一个演示组件、一个单插件 Vite 配置、一份两条规则的 Oxlint 配置，配合 @vitejs/plugin-react（Oxc）实现 HMR，同时把 React Compiler、TypeScript、类型感知 lint 都作为显式的可选路径留给使用者按需升级（react-ts / react-compiler-ts 模板）。关键参考文件：