企业官网建设流程全解析

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能

导读

本篇技术指南围绕 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md 这一条 React 性能与正确性规范展开，说明为什么"每次挂载都执行的应用级初始化"是错误的，以及如何用模块级守卫（module-level guard）或入口模块（entry module）顶层初始化，让loadFromStorage()、checkAuthToken()这类初始化逻辑在每次应用加载（app load）中只运行一次。读完本文，你将掌握在 Phoenix 这类大型 React 前端（js/app）中识别重复初始化、消除开发环境双重执行、避免组件重挂载引发副作用重放的完整方法，并能结合仓库真实代码（如 js/app/src/index.tsx、js/app/src/App.tsx）验证落地效果。

规则出处与定位

该规范是仓库内 Vercel React Best Practices 技能包（.agents/skills/vercel-react-best-practices）中Advanced Patterns（高级模式）章节的第 8.2 条规则，位于 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md，其 frontmatter 元数据为：

title: Initialize App Once, Not Per Mount impact: LOW-MEDIUM impactDescription: avoids duplicate init in development tags: initialization, useEffect, app-startup, side-effects

从技能包的分类体系看（见 SKILL.md），advanced-前缀对应 "Advanced Patterns" 分类，是 8 个类别中优先级最低的一档，但LOW-MEDIUM的影响等级意味着：虽然收益并非每次都能肉眼可见，但在开发模式下几乎必然触发——这正是该规则"低成本、高确定性收益"的特点。该规则已被构建进编译后的完整指南 .agents/skills/vercel-react-best-practices/AGENTS.md，ID 为8.2，供 Agent 和 LLM 在审查、重构 React 代码时直接引用。

核心问题：useEffect([])不等于"只执行一次"

React 组件在以下场景中会重新挂载（remount），导致useEffect([])的副作用全部重放：

• 父组件通过 key 改变强制重建子树；
• 组件在条件渲染（show && <Comp/>）中反复进出；
• 路由切换导致页面组件卸载后再挂载；
• React StrictMode 在开发模式下主动双调用挂载流程以暴露副作用不纯的问题（这也是"开发环境执行两次"的最常见来源）；
• 兄弟组件位置变化引发的协调重建。

因此，把"整个应用只应初始化一次"的逻辑写进任意组件的useEffect([])，等于把应用生命周期错误地绑定在了某个组件的挂载生命周期上。一旦该组件重挂载，loadFromStorage()会重复读取、checkAuthToken()会重复请求，轻则浪费 IO 与网络，重则引发状态覆盖、重复订阅、重复埋点等难以排查的 bug。

错误写法（开发环境跑两次、重挂载再跑）

原文档给出的反模式示例：

function Comp() { useEffect(() => { loadFromStorage() checkAuthToken() }, []) // ... }

问题要点：

1. 开发模式双执行：React StrictMode 会 mount → unmount → remount，该 effect 立即运行两次；
2. 重挂载重放：路由切换、条件渲染让Comp重新挂载时，初始化逻辑再次全量执行；
3. 职责错位：初始化属于"应用级"职责，却被耦合进"组件级"生命周期。

正确写法：模块级守卫（module-level guard）

原文档推荐的修复方案：

let didInit = false function Comp() { useEffect(() => { if (didInit) return didInit = true loadFromStorage() checkAuthToken() }, []) // ... }

原理说明：

• didInit是模块作用域变量（module-level variable），其生命周期等于模块实例的生命周期，即一次应用加载只创建一份；
• 第一次进入 effect 时didInit置为true，后续无论组件如何重挂载、effect 如何重放，守卫都会直接短路返回；
• 代码仍保留在useEffect中，因而能访问组件闭包，又通过模块级状态保证了幂等性。

更彻底的方案：入口模块顶层初始化

如果初始化逻辑不依赖组件闭包（不访问 props、state、ref），可以干脆把它提到入口模块（entry module）顶层，在createRoot().render()之前同步执行，连 effect 都不需要：

// main.tsx import ReactDom from "react-dom/client"; // 顶层初始化：模块加载时仅执行一次 loadFromStorage() checkAuthToken() const rootEl = document.getElementById("root"); const root = ReactDom.createRoot(rootEl!); root.render(<App />);

模块顶层代码在模块首次被 import 求值时运行且只运行一次，天然满足"per app load"语义，不受 React 渲染机制任何影响。

仓库实证：Phoenix 前端的入口初始化结构

Phoenix 前端的应用入口 js/app/src/index.tsx 正是"入口模块顶层初始化 + createRoot 渲染"这一模式的真实样例：

import ReactDom from "react-dom/client"; import { App } from "./App"; // 模块级副作用：Vite modulepreload polyfill 与全局样式 import "vite/modulepreload-polyfill"; import "./styles/cascade-layers.css"; const rootEl = document.getElementById("root"); const root = ReactDom.createRoot(rootEl!); root.render(<App />);

可以看到：

• import "vite/modulepreload-polyfill"与import "./styles/cascade-layers.css"都是模块加载即执行的全局副作用，属于典型的顶层初始化；
• createRoot(rootEl!)与root.render(<App />)在模块顶层完成，确保应用只挂载一次；
• 从源码结构看，Phoenix 特意绕开 HTML 自定义入口、由服务端渲染 index.html 后由该文件接管挂载，因此把这类初始化放在入口模块顶层而非某个组件内部，是保证"一次加载只初始化一次"的关键（注释见 js/app/src/index.tsx）。

组件树则被收敛在 js/app/src/App.tsx，由FunctionalityProvider、ThemeProvider、RelayEnvironmentProvider、FeatureFlagsProvider、PreferencesProvider、CredentialsProvider等 Provider 逐层包裹，所有 Provider 都在渲染树内部工作，没有任何一个承担"应用级一次性初始化"的职责——这正是本规则提倡的职责划分：初始化在入口，Provider 只负责渲染期数据流。

何时使用"模块级守卫"而不是"入口初始化"

两种方案的选择依据可以归纳为一张表：

需要特别强调的是第三条：本规则针对的是"应用级、全局唯一"的初始化。如果某段副作用本就该随组件挂载而执行（如订阅、测量），则不应套用模块级守卫，否则会造成"组件 A 卸载后全局状态残留"的新问题。从仓库看，Phoenix 的 Drawer.tsx 中hasInitializedContainerSizeRef = useRef(frame == null)与useLayoutEffect的组合，就是"仅初始化一次"在组件实例级的正确做法——它用 ref 而非模块变量，因为抽屉尺寸初始化必须随组件生命周期重置，这从反面印证了模块级守卫只适合"应用级初始化"的边界。

与相邻规则的协同：完整的高级模式工具箱

本规则并非孤例，它是高级模式（Advanced Patterns）章节 4 条规则之一，与其余 3 条共同覆盖"副作用与生命周期"这一主题（见 SKILL.md 与 AGENTS.md 第 8 章）：

若初始化逻辑中恰好包含"以最新回调处理事件"的需求（如初始化时注册全局监听），可组合参考 advanced-event-handler-refs.md：将回调存入 ref，订阅 effect 只依赖事件名，从而在"只初始化一次"的同时不丢失最新闭包。

工程落地建议

1. 新代码默认走入口：凡是loadFromStorage、checkAuthToken、主题恢复、埋点 SDK 初始化、全局事件注册等应用级副作用，一律放到入口模块顶层或在首个组件中以didInit守卫包裹，并在注释中写明"intentional: runs once per app load"。
2. 审查useEffect([])清单：代码评审时逐个检查空依赖数组 effect，自问"这段逻辑如果组件重挂载再跑一次，会造成什么后果？"——会出问题就必须加守卫或上提。
3. 注意 StrictMode 双调用：开发环境"跑两次"不是缺陷，而是 React 故意暴露非幂等副作用的手段；用模块级守卫消化它，比移除 StrictMode 更符合规范。
4. 区分层级：应用级用模块守卫，组件级用useRef守卫（如 Phoenix 的 Drawer.tsx），切勿混用导致状态泄漏。
5. 配合 CI/Agent 审查：该技能包本身就是为 Agent 与 LLM 审查代码设计的，可将advanced-init-once规则加入 React 代码审查提示词（参考 SKILL.md 的 When to Apply 列表），让自动化审查在编写阶段就拦截重复初始化。

总结

"应用只初始化一次"是 React 应用中一个常被忽视的正确性细节：useEffect([])绑定的是组件挂载生命周期，而非应用加载生命周期。通过模块级didInit守卫或入口模块顶层初始化，可以让loadFromStorage()、checkAuthToken()等逻辑严格遵循"per app load"语义，同时天然兼容 StrictMode 的开发环境双调用。Phoenix 仓库的 js/app/src/index.tsx 已经示范了入口模块顶层初始化的工程形态，而 advanced-event-handler-refs 等相邻规则则补全了"一次性初始化 + 稳定订阅"的完整实践。掌握并落实这一条规则，是让 React 应用在开发与生产环境行为一致、避免隐式重复副作用的基础功之一。

• 可观测性
• AI 评测
• LLMOps
• AI 应用
• 人工智能