Vite React 插件：在 Vite 中組合 JSX、Fast Refresh 與 React 編译选項
vite-plugin-react 是 React 的官方 Vite 集成，提供快速刷新、JSX/TSX 支援、SWC 轉換和固執己見的 React 插件體驗。
秒懂
- 它是什麼？
- vitejs/vite-plugin-react 倉庫维护 `@vitejs/plugin-react`、SWC 版本和 RSC 插件，分別通過 README 與包目录文檔說明配置边界。
- 適合誰用？
- 适合使用 Vite 構建 React 或 RSC 應用、需要開發期快速刷新的項目；不适合忽略 SSR preamble、include/exclude 或運行時版本约束的迁移。先安装对應包並檢查 `vite.config`，再用一次編輯、一次 SSR 请求和生產構建确认行為。
- 可以商用嗎？
- 可以。MIT 是寬鬆授權：你可以使用、修改並販售以它為基礎的軟體，只需保留著作權與授權聲明。
- 還在維護嗎？
- 有在維護。儲存庫最近一次提交在 1 天前。
- 用什麼語言寫的？
- 主要是 TypeScript（依據 GitHub 的語言統計）。
以上回答依據專案的 GitHub 資料（最近同步於 2026年9月14日）與我們的分析，不構成法律意見。
開源專案深度解析
插件概述與快速開始 · vitejs-vite-plugin-react-deep-analysis
@vitejs/plugin-react 是 Vite 項目中用于 React 的默认插件，其倉庫描述為「The all-in-one Vite plugin for React projects」，並在 README 中自稱默认插件。它主要提供三項核心能力：在開發環境中啟用 Fast Refresh（需要 React 版本不低于 16.9）、使用自動 JSX 運行時，以及保持较小的安装體积。要啟用该插件，可以在 Vite 配置文件中導入 react 函數並將其加入 plugins 數組，例如 vite.config.js 中的默认配置。该插件以 TypeScript 編寫，遵循 MIT 許可證，当前倉庫有 1133 個星標和 261 個 fork，但 README 未提及具體版本號或與其他插件的性能对比。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
include 與 exclude 选項 · vitejs-vite-plugin-react-deep-analysis
插件默认会處理 .js、.jsx、.ts 和 .tsx 文件。通過 include 选項，可以扩展 Fast Refresh 的适用范围，比如將 .mdx 文件纳入處理，示例中結合 @mdx-js/rollup 插件並在 react 配置中传入正则表达式 /。(mdx|js|jsx|ts|tsx)$/。exclude 选項默认值為 /node_modules/，用于排除那些不需要 Fast Refresh 的文件，例如運行在 worker 中的 JSX/TSX 文件或非 React 文件。README 特別提醒，除非有明确需求，否则應保留 node_modules 在排除列表中，示例中展示了同時排除 /pdf/ 和 .solid.tsx 文件的寫法。這两個选項都通過正则或數組形式控制插件的作用范围。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
JSX 運行時配置 · vitejs-vite-plugin-react-deep-analysis
插件默认使用自動 JSX 運行時，但提供了 jsxRuntime 选項，可以切换回 classic 模式，以應对某些情况下的兼容問題。另外，jsxImportSource 选項用于控制 JSX factory 的導入來源，默认会根據对應文件的 tsconfig 中的 jsxImportSource 推断，示例中設置為 @emotion/react。這两個选項赋予開發者对 JSX 转换過程的精细控制，特別是当項目使用 Emotion 等庫或需要兼容旧版 React 環境時。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
React Compiler 預設 · vitejs-vite-plugin-react-deep-analysis
React Compiler 的支持通過導出的 reactCompilerPreset 辅助函數提供，该函數需要 @rolldown/plugin-babel、babel-plugin-react-compiler 和 @babel/core 作為 peer dependencies。使用 TypeScript 時還需安装 @types/babel__core。配置示例展示了如何在 vite.config.js 中同時使用 react() 和 babel({ presets: [reactCompilerPreset()] })。預設接受可选參數 compilationMode，設置為 annotation 時僅編译带有 "use memo" 注釋的組件；target 选項可設置為 '17' 或 '18' 以针对旧版 React，此時会使用 react-compiler-runtime 而非 react/compiler-runtime。另外，預設是預配置過滤器的便捷助手，可通過修改其 rolldown.filter 属性來自定義排除范围，例如排除 src/legacy/** 等目录。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
SSR 中的 preamble 處理 · vitejs-vite-plugin-react-deep-analysis
对于不使用 transformIndexHtml API 的 SSR 應用，插件提供了 @vitejs/plugin-react/preamble 子路径，用于從客户端入口初始化 HMR 運行時。示例中在 entry.client.js 中直接導入该模块。另一种方式是手動調用 viteServer.transformIndexHtml 來生成等效的初始化代码，README 给出了 Express 服務器的示例。如果缺少 preamble 初始化，運行時会出現錯誤："Uncaught Error: @vitejs/plugin-react can't detect preamble. Something is wrong." 此部分說明了 SSR 场景下的特殊需求，並提供了两种解决方案。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
組件導出一致性與快速刷新 · vitejs-vite-plugin-react-deep-analysis
為了确保 React Fast Refresh 正常工作，文件應僅導出 React 組件，否则模块可能失效並導致 HMR 传播。如果文件包含常量等其他導出，只有在值變化時才会失效，這樣可以方便地導出简单常量。README 引用了 Gatsby 文檔解釋其工作原理，並推荐使用 ESLint、Oxlint 或 Biome 的规则來捕獲錯誤並獲取更详细的警告。這一部分提醒開發者注意文件結構对 Fast Refresh 的影响，並提供了可选的 lint 工具。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
許可證與驗證事項 · vitejs-vite-plugin-react-deep-analysis
该倉庫遵循 MIT 許可證，版權归 Yuxi (Evan) You 和 Vite 贡献者所有，許可證文本明确允許使用、复制、修改、合並、發布、分發、再許可和销售軟件副本，但軟件按「AS IS」提供，不附带任何明示或暗示的担保，包括适销性、特定用途适用性和非侵權性。許可證未提及安全支持、更新承诺或商业支持。README 也未提供插件版本號、與其他插件的性能对比、生產環境測試結果或安全审計信息，這些内容如需确认，應查阅官方發布记录或進行独立驗證。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。 vitejs-vite-plugin-react-deep-analysis 的判斷不能脫離專案本身。應把 README 提到的入口、設定鍵與輸出格式放進最小可行案例，記錄成功與失敗的差異；若文件未說明某項行為，就把它列為未知，而不是推定預設值。這對依賴版本、作業系統、模型、瀏覽器或 Android 執行環境的功能尤其重要。
編輯結論
适合使用 Vite 構建 React 或 RSC 應用、需要開發期快速刷新的項目；不适合忽略 SSR preamble、include/exclude 或運行時版本约束的迁移。先安装对應包並檢查 `vite.config`，再用一次編輯、一次 SSR 请求和生產構建确认行為。 對 vitejs-vite-plugin-react-deep-analysis 而言，先在隔離環境執行 README 指定的安裝或啟動命令，觀察實際輸出、錯誤訊息與設定檔，再決定是否納入正式流程。
社群筆記