React/Next.js 应用级初始化只执行一次Plate 仓库中 init-once 模式的规则解析与实践【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本篇围绕 Plate 仓库内置的 React 最佳实践技能中的advanced-init-once规则展开讲解为什么应用级初始化如读取本地存储、校验认证 Token不应放进组件的useEffect([])以及如何用模块级守卫或入口模块顶层初始化保证“每次应用加载只执行一次”。读完你能掌握该规则的判定标准、两种正确写法的取舍以及它在这套规则体系中的工程化定位。规则在仓库中的定位该规则文件位于 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md属于 Vercel 工程团队维护的 “React Best Practices” 技能的一部分。根据 SKILL.md该技能包含 8 大类共 69 条规则按影响程度排序advanced-前缀的“Advanced Patterns”位列第 8 类影响等级 LOW适用于编写、评审或重构 React/Next.js 代码的场景。规则文件采用统一的 frontmatter 元数据格式advanced-init-once的元数据为--- title: Initialize App Once, Not Per Mount impact: LOW-MEDIUM impactDescription: avoids duplicate init in development tags: initialization, useEffect, app-startup, side-effects ---impact: LOW-MEDIUM影响等级介于低到中。从 impactDescription 可以看出该规则的核心收益是避免在开发环境中出现重复初始化属于正确性与开发体验问题而非大规模性能问题因此优先级不高但不容忽视。按 README.md 的约定规则文件以area-description.md命名此处为advanced-init-once.md所属分区由文件名前缀自动推断执行pnpm build后会编译进AGENTS.md。事实上在编译产物 .agents/skills/vercel-react-best-practices/AGENTS.md 中该规则被编号为 “8.2 Initialize App Once, Not Per Mount”。分区定义见 rules/_sections.mdAdvanced Patterns 分区说明其定位是“针对特定场景、需要谨慎实现的进阶模式”与 init-once 这种需要理解模块生命周期才能用对的规则相符。反模式把应用级初始化放进useEffect([])规则的核心主张是必须每次应用加载只运行一次的应用级初始化不要放在组件的useEffect([])里。组件可能被重新挂载remount而 effect 会随之重新执行。原文档给出的反例如下function Comp() { useEffect(() { loadFromStorage() checkAuthToken() }, []) // ... }这个写法的问题有两层原文档明确标注其“在开发环境下运行两次且在 remount 时再次运行”开发环境下的重复执行。React 18 起开发模式下 StrictMode 会故意对组件进行挂载-卸载-再挂载的演练以暴露不幂等的生命周期逻辑。此时同一个useEffect([])的初始化代码会被触发两次。如果loadFromStorage()或checkAuthToken()内部带有计数、埋点上报、WebSocket 建连等副作用就会产生重复行为。组件重新挂载后的再次执行。useEffect([])的语义是“本组件实例挂载时执行”而不是“应用启动时执行”。在单页应用中路由切换导致组件卸载再挂载、父组件条件渲染{show Comp/}导致子树重建、错误边界兜底后重新挂载等场景都会让 effect 重新跑一遍。对于“全局只需一次”的初始化读取本地存储、校验 Token、初始化全局单例来说这既浪费资源也可能引发竞态例如并发两次认证检查。在 Plate 这样的 Next.js 多包 monorepo 中apps/www 是基于 Next.js 的文档站与示例应用页面间导航会频繁地挂载和卸载包含编辑器实例的页面组件。可以推断在此类站点中若将埋点上报、主题存储读取等应用级初始化放在某个页面组件的useEffect([])中随着用户浏览多个文档页与示例页初始化会被反复触发——这正是该规则要规避的形态。正确写法一模块级守卫module-level guard规则给出的正确示例是在模块作用域放一个布尔守卫let didInit false function Comp() { useEffect(() { if (didInit) return didInit true loadFromStorage() checkAuthToken() }, []) // ... }这种写法的关键在于didInit声明在模块顶层而非组件内部。JavaScript 模块在同一个 JS 运行时中只会被求值一次模块注册表按模块 URL 去重因此didInit是一个天然的“进程内单例”状态组件第一次挂载时effect 执行初始化并把didInit置为true开发环境 StrictMode 的二次挂载、或后续任何 remounteffect 虽然会再次进入函数体但第一行if (didInit) return会立即短路初始化只真正发生一次。需要注意的边界模块级状态的生命周期与模块本身一致。从源码结构看前端构建工具在热更新HMR时通常会保留已加载模块的状态也就是说开发中保存文件触发的局部 HMR 不会重置didInit只有整页刷新模块重新求值才会重新初始化——这恰好符合“每次应用加载一次”的语义。另外该守卫只保证“同一 JS 上下文内一次”并不解决多标签页共享状态的问题若多个标签页都需访问初始化结果应依赖本地存储等持久化介质而非内存变量。正确写法二入口模块顶层初始化规则同样推荐“在入口模块做顶层初始化top-level init in the entry module”。其思路是既然初始化与某个组件的生命周期无关就把它移出组件树放到应用入口如 Next.js 应用中的根布局/Provider 所在模块或独立的前置初始化模块的模块顶层直接执行// entry.ts示意入口模块顶层模块求值时执行一次 import { loadFromStorage } from /lib/storage import { checkAuthToken } from /lib/auth loadFromStorage() checkAuthToken()两种正确写法的取舍可以归纳为写法执行时机适用场景模块级守卫 useEffect组件挂载后浏览器端初始化依赖浏览器 API如 localStorage、DOM必须确认运行在客户端且希望在 hydration 之后进行入口模块顶层执行模块求值时最早不依赖组件生命周期的纯逻辑初始化或需要尽早完成的配置装配需要特别警惕的是入口顶层执行与 SSR 的交互在服务端渲染过程中入口模块的顶层代码会在服务器上被求值此时window、localStorage等浏览器 API 并不存在。因此凡涉及浏览器环境的初始化读取本地存储、校验 Token要么保留在客户端 effect 中用模块级守卫保护要么在顶层代码中做环境判断。这一点与同一技能中的 rules/server-no-shared-module-state.md 形成呼应——该规则提醒避免在 RSC/SSR 中使用模块级可变请求状态。换言之模块级守卫是客户端“一次性”初始化的惯用手段但在服务端上下文中模块级状态有跨请求共享的风险两类规则的适用边界必须区分清楚。与同族 Advanced 规则的关系advanced-init-once与另外三条 Advanced 规则同属“生命周期与副作用精细控制”这一主题族可对照理解rules/advanced-use-latest.md用useLatest获取稳定的最新回调引用避免 effect 因回调变化反复重跑rules/advanced-effect-event-deps.mduseEffectEvent返回的函数身份每次渲染都变化不应放入useEffect依赖数组rules/advanced-event-handler-refs.md把事件处理器存入 ref 以获得稳定引用。它们共同指向一个判断框架先区分“与组件生命周期绑定的逻辑”放进 effect且依赖要正确和“与应用生命周期绑定的逻辑”移出组件用模块级状态或入口顶层表达。init-once 正是第二类的典型代表——认证检查、存储水合、全局单例装配这类逻辑的语义主体是“应用加载”这个事件而不是“某组件挂载”这个事件把它放进useEffect([])是用错了抽象层级。工程化落地规则如何被构建与校验这套规则不止是文档而是一条可执行的工具链。按 README.md 的说明pnpm install安装依赖pnpm build将rules/下所有规则文件编译为AGENTS.md规则按标题在分区内自动排序编号自动生成pnpm validate校验所有规则文件的格式pnpm extract-tests从规则中提取用于 LLM 评估的测试用例test-cases.json。因此advanced-init-once.md中的“Incorrect/Correct 代码对照 一句话理由 frontmatter 元数据”这一格式不是随意的排版而是模板 rules/_template.md 的强制结构目的是让 Agent 与 LLM 能以统一方式解析、引用和测试每条规则。对实际开发者的可操作结论是评审代码时凡看到组件useEffect([])中出现与组件自身状态无关的全局副作用加载全局配置、校验认证、注册全局监听应优先质疑其是否应为应用级初始化若确认是一次性初始化改用模块级didInit守卫或将其上移到入口模块顶层注意 SSR 环境判断;该规则影响等级为 LOW-MEDIUM收益主要体现在开发环境正确性上但它能避免的重复认证、重复上报问题在线上 remount 场景同样存在值得作为代码评审 checklist 的固定条目。小结advanced-init-once规则用极简的代码对照揭示了一个容易混淆的生命周期问题useEffect([])的承诺是“本组件挂载时”而应用级初始化需要的是“本应用加载时”。模块级守卫利用模块求值一次的运行时特性补齐了这一语义缺口入口模块顶层初始化则干脆把问题移出组件体系。在 Plate 这类 Next.js 站点与编辑器示例密集的仓库中这两类写法是控制启动期副作用的最直接手段而同一技能中的服务端模块状态规则又划定了它的边界——客户端的“一次性守卫”不要照搬进 SSR 的请求上下文。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
React/Next.js 应用级初始化只执行一次Plate 仓库中 init-once 模式的规则解析与实践【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate本篇围绕 Plate 仓库内置的 React 最佳实践技能中的advanced-init-once规则展开讲解为什么应用级初始化如读取本地存储、校验认证 Token不应放进组件的useEffect([])以及如何用模块级守卫或入口模块顶层初始化保证“每次应用加载只执行一次”。读完你能掌握该规则的判定标准、两种正确写法的取舍以及它在这套规则体系中的工程化定位。规则在仓库中的定位该规则文件位于 .agents/skills/vercel-react-best-practices/rules/advanced-init-once.md属于 Vercel 工程团队维护的 “React Best Practices” 技能的一部分。根据 SKILL.md该技能包含 8 大类共 69 条规则按影响程度排序advanced-前缀的“Advanced Patterns”位列第 8 类影响等级 LOW适用于编写、评审或重构 React/Next.js 代码的场景。规则文件采用统一的 frontmatter 元数据格式advanced-init-once的元数据为--- title: Initialize App Once, Not Per Mount impact: LOW-MEDIUM impactDescription: avoids duplicate init in development tags: initialization, useEffect, app-startup, side-effects ---impact: LOW-MEDIUM影响等级介于低到中。从 impactDescription 可以看出该规则的核心收益是避免在开发环境中出现重复初始化属于正确性与开发体验问题而非大规模性能问题因此优先级不高但不容忽视。按 README.md 的约定规则文件以area-description.md命名此处为advanced-init-once.md所属分区由文件名前缀自动推断执行pnpm build后会编译进AGENTS.md。事实上在编译产物 .agents/skills/vercel-react-best-practices/AGENTS.md 中该规则被编号为 “8.2 Initialize App Once, Not Per Mount”。分区定义见 rules/_sections.mdAdvanced Patterns 分区说明其定位是“针对特定场景、需要谨慎实现的进阶模式”与 init-once 这种需要理解模块生命周期才能用对的规则相符。反模式把应用级初始化放进useEffect([])规则的核心主张是必须每次应用加载只运行一次的应用级初始化不要放在组件的useEffect([])里。组件可能被重新挂载remount而 effect 会随之重新执行。原文档给出的反例如下function Comp() { useEffect(() { loadFromStorage() checkAuthToken() }, []) // ... }这个写法的问题有两层原文档明确标注其“在开发环境下运行两次且在 remount 时再次运行”开发环境下的重复执行。React 18 起开发模式下 StrictMode 会故意对组件进行挂载-卸载-再挂载的演练以暴露不幂等的生命周期逻辑。此时同一个useEffect([])的初始化代码会被触发两次。如果loadFromStorage()或checkAuthToken()内部带有计数、埋点上报、WebSocket 建连等副作用就会产生重复行为。组件重新挂载后的再次执行。useEffect([])的语义是“本组件实例挂载时执行”而不是“应用启动时执行”。在单页应用中路由切换导致组件卸载再挂载、父组件条件渲染{show Comp/}导致子树重建、错误边界兜底后重新挂载等场景都会让 effect 重新跑一遍。对于“全局只需一次”的初始化读取本地存储、校验 Token、初始化全局单例来说这既浪费资源也可能引发竞态例如并发两次认证检查。在 Plate 这样的 Next.js 多包 monorepo 中apps/www 是基于 Next.js 的文档站与示例应用页面间导航会频繁地挂载和卸载包含编辑器实例的页面组件。可以推断在此类站点中若将埋点上报、主题存储读取等应用级初始化放在某个页面组件的useEffect([])中随着用户浏览多个文档页与示例页初始化会被反复触发——这正是该规则要规避的形态。正确写法一模块级守卫module-level guard规则给出的正确示例是在模块作用域放一个布尔守卫let didInit false function Comp() { useEffect(() { if (didInit) return didInit true loadFromStorage() checkAuthToken() }, []) // ... }这种写法的关键在于didInit声明在模块顶层而非组件内部。JavaScript 模块在同一个 JS 运行时中只会被求值一次模块注册表按模块 URL 去重因此didInit是一个天然的“进程内单例”状态组件第一次挂载时effect 执行初始化并把didInit置为true开发环境 StrictMode 的二次挂载、或后续任何 remounteffect 虽然会再次进入函数体但第一行if (didInit) return会立即短路初始化只真正发生一次。需要注意的边界模块级状态的生命周期与模块本身一致。从源码结构看前端构建工具在热更新HMR时通常会保留已加载模块的状态也就是说开发中保存文件触发的局部 HMR 不会重置didInit只有整页刷新模块重新求值才会重新初始化——这恰好符合“每次应用加载一次”的语义。另外该守卫只保证“同一 JS 上下文内一次”并不解决多标签页共享状态的问题若多个标签页都需访问初始化结果应依赖本地存储等持久化介质而非内存变量。正确写法二入口模块顶层初始化规则同样推荐“在入口模块做顶层初始化top-level init in the entry module”。其思路是既然初始化与某个组件的生命周期无关就把它移出组件树放到应用入口如 Next.js 应用中的根布局/Provider 所在模块或独立的前置初始化模块的模块顶层直接执行// entry.ts示意入口模块顶层模块求值时执行一次 import { loadFromStorage } from /lib/storage import { checkAuthToken } from /lib/auth loadFromStorage() checkAuthToken()两种正确写法的取舍可以归纳为写法执行时机适用场景模块级守卫 useEffect组件挂载后浏览器端初始化依赖浏览器 API如 localStorage、DOM必须确认运行在客户端且希望在 hydration 之后进行入口模块顶层执行模块求值时最早不依赖组件生命周期的纯逻辑初始化或需要尽早完成的配置装配需要特别警惕的是入口顶层执行与 SSR 的交互在服务端渲染过程中入口模块的顶层代码会在服务器上被求值此时window、localStorage等浏览器 API 并不存在。因此凡涉及浏览器环境的初始化读取本地存储、校验 Token要么保留在客户端 effect 中用模块级守卫保护要么在顶层代码中做环境判断。这一点与同一技能中的 rules/server-no-shared-module-state.md 形成呼应——该规则提醒避免在 RSC/SSR 中使用模块级可变请求状态。换言之模块级守卫是客户端“一次性”初始化的惯用手段但在服务端上下文中模块级状态有跨请求共享的风险两类规则的适用边界必须区分清楚。与同族 Advanced 规则的关系advanced-init-once与另外三条 Advanced 规则同属“生命周期与副作用精细控制”这一主题族可对照理解rules/advanced-use-latest.md用useLatest获取稳定的最新回调引用避免 effect 因回调变化反复重跑rules/advanced-effect-event-deps.mduseEffectEvent返回的函数身份每次渲染都变化不应放入useEffect依赖数组rules/advanced-event-handler-refs.md把事件处理器存入 ref 以获得稳定引用。它们共同指向一个判断框架先区分“与组件生命周期绑定的逻辑”放进 effect且依赖要正确和“与应用生命周期绑定的逻辑”移出组件用模块级状态或入口顶层表达。init-once 正是第二类的典型代表——认证检查、存储水合、全局单例装配这类逻辑的语义主体是“应用加载”这个事件而不是“某组件挂载”这个事件把它放进useEffect([])是用错了抽象层级。工程化落地规则如何被构建与校验这套规则不止是文档而是一条可执行的工具链。按 README.md 的说明pnpm install安装依赖pnpm build将rules/下所有规则文件编译为AGENTS.md规则按标题在分区内自动排序编号自动生成pnpm validate校验所有规则文件的格式pnpm extract-tests从规则中提取用于 LLM 评估的测试用例test-cases.json。因此advanced-init-once.md中的“Incorrect/Correct 代码对照 一句话理由 frontmatter 元数据”这一格式不是随意的排版而是模板 rules/_template.md 的强制结构目的是让 Agent 与 LLM 能以统一方式解析、引用和测试每条规则。对实际开发者的可操作结论是评审代码时凡看到组件useEffect([])中出现与组件自身状态无关的全局副作用加载全局配置、校验认证、注册全局监听应优先质疑其是否应为应用级初始化若确认是一次性初始化改用模块级didInit守卫或将其上移到入口模块顶层注意 SSR 环境判断;该规则影响等级为 LOW-MEDIUM收益主要体现在开发环境正确性上但它能避免的重复认证、重复上报问题在线上 remount 场景同样存在值得作为代码评审 checklist 的固定条目。小结advanced-init-once规则用极简的代码对照揭示了一个容易混淆的生命周期问题useEffect([])的承诺是“本组件挂载时”而应用级初始化需要的是“本应用加载时”。模块级守卫利用模块求值一次的运行时特性补齐了这一语义缺口入口模块顶层初始化则干脆把问题移出组件体系。在 Plate 这类 Next.js 站点与编辑器示例密集的仓库中这两类写法是控制启动期副作用的最直接手段而同一技能中的服务端模块状态规则又划定了它的边界——客户端的“一次性守卫”不要照搬进 SSR 的请求上下文。【免费下载链接】plateRich-text editor with AI and shadcn/ui项目地址: https://gitcode.com/GitHub_Trending/pl/plate创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
