open-agents React 性能规则实战应用级初始化只执行一次而不是每次挂载都执行【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents本篇基于 open-agents 仓库内置的 Vercel React 最佳实践规则集深入讲解advanced-init-once应用只初始化一次而非按组件挂载次数初始化这条规则先继承规则原文的反模式/正确模式对比再结合本仓库中instrumentation-client.ts、skills-cache.ts、chat-instance-manager.ts等真实源码拆解入口模块顶层初始化与模块级守卫两种落地形态的适用边界与注意事项。规则的来源与定位Vercel 最佳实践规则集中的 advanced-init-onceopen-agents 在 .agents/skills/vercel-react-best-practices/ 目录下内置了一套面向 Agent 与 LLM 结构化的 React/Next.js 性能规则库。根据 SKILL.md这套规则共 58 条、分 8 个类别按影响程度排序优先级类别影响文件前缀1消除串行等待WaterfallsCRITICALasync-2包体积优化CRITICALbundle-3服务端性能HIGHserver-4客户端数据获取MEDIUM-HIGHclient-5重渲染优化MEDIUMrerender-6渲染性能MEDIUMrendering-7JavaScript 性能LOW-MEDIUMjs-8高级模式Advanced PatternsLOWadvanced-本文的主题 advanced-init-once.md 属于第 8 类高级模式与advanced-event-handler-refs、advanced-use-latest并列。其 frontmatter 元信息为title: Initialize App Once, Not Per Mountimpact: LOW-MEDIUM —— 按 README.md 中影响等级定义属于低到中等收益其impactDescription明确写道avoids duplicate init in development避免在开发环境中重复初始化tags:initialization, useEffect, app-startup, side-effects该规则集对每条规则采用统一的结构frontmatter 元信息 规则说明 Incorrect 反例 Correct 正例 参考链接并通过pnpm build编译进 AGENTS.md。下面继承规则原文的核心内容再展开原理与仓库内的真实落地。规则核心不要将应用级初始化放进组件的 useEffect规则的原始表述是不要将必须每次应用加载只运行一次的应用级初始化放进组件的useEffect([])中。组件可能被重新挂载remount而 effect 会随之重新执行应改用模块级守卫module-level guard或在入口模块的顶层执行初始化。反模式开发模式下执行两次且组件重挂载时再次执行function Comp() { useEffect(() { loadFromStorage() checkAuthToken() }, []) // ... }正确写法每次应用加载只执行一次let didInit false function Comp() { useEffect(() { if (didInit) return didInit true loadFromStorage() checkAuthToken() }, []) // ... }两个要点值得展开为什么开发模式下执行两次React 在开发模式下StrictMode会对挂载 effect 做双重调用以暴露副作用代码中不可安全重放的问题。把 SDK 初始化、鉴权检查、本地存储读取这类一次性副作用写进useEffect([])在开发环境就会触发两次一旦组件因为路由切换、条件渲染、错误边界恢复等原因重新挂载effect 还会第三次、第四次执行。模块级守卫为什么有效didInit是挂在模块命名空间上的变量。组件卸载/重挂载不会重置模块状态因此守卫在整个页面生命周期内稳定。这也是规则把两种方案并列推荐的原因——模块级守卫是保守改法改动最小适合无法移动代码的场景而入口模块顶层初始化是更彻底的推荐改法模块代码在浏览器端每次页面加载只执行一次天然满足once per app load语义连 effect 都不需要。规则原文还指向了 React 官方文档《You Might Not Need an Effect》中的 Initializing the application 一节作为权威参考。open-agents 仓库中的真实落地三种只执行一次的形态本仓库在 Next.js App Router 架构下恰好完整覆盖了这条规则的三种落地形态下面逐一对照源码。形态一入口模块顶层初始化规则推荐的正解apps/web/instrumentation-client.ts 是客户端 instrumentation 入口文件其中 Vercel BotID 的客户端初始化直接写在模块顶层import { initBotId } from botid/client/core; export const botIdProtectedRoutes [ // AI text-generation endpoints { path: /api/chat, method: POST }, { path: /api/generate-pr, method: POST }, // ... ]; /** * Vercel BotID client-side initialization. * * Declares which routes require bot-detection challenge headers so the * server-side checkBotId() calls in each handler can verify the request. */ initBotId({ protect: botIdProtectedRoutes, });这里initBotId(...)的调用不依赖任何组件、任何 effect模块被加载的那一刻即客户端入口初始化阶段就完成注册天然满足每次应用加载只执行一次且与 UI 生命周期完全解耦。对应的 instrumentation-client.test.ts 直接import(./instrumentation-client)后断言botIdProtectedRoutes的内容验证了该入口模块可独立导入、无副作用泄漏的工程质量。这正是规则所倡导的top-level init in the entry module的直接实现。形态二模块级懒创建单例守卫比布尔量更强的守卫apps/web/lib/skills-cache.ts 展示了模块级守卫的进阶形态——三态懒单例第 27–41 行let sharedRedisClient: SkillsCacheRedisClient | null | undefined; function getSharedRedisClient(): SkillsCacheRedisClient | null { if (sharedRedisClient ! undefined) { return sharedRedisClient; } if (!isRedisConfigured()) { sharedRedisClient null; return sharedRedisClient; } sharedRedisClient createRedisClient(skills-cache); return sharedRedisClient; }这里用undefined / null / 客户端实例三个状态区分尚未尝试创建/已尝试但环境未配置 Redis永久失败无需重试/已成功创建。相比规则示例中的布尔didInit它把守卫从只执行一次扩展为只初始化一次 记住初始化结果首次调用getSharedRedisClient()时才真正创建 ioredis 客户端通过createRedisClient(skills-cache)后续调用直接复用未配置REDIS_URL/KV_URL时降级为内存缓存并记录一次错误日志。模块底部同样以const sharedSkillsCache createSkillsCache()第 267 行暴露全局单例缓存对外提供getCachedSkills/setCachedSkills。形态三模块级共享状态 一次性副作用去重同一条规则思想还体现在共享状态放在模块上、副作用只发生一次的工程约定中apps/web/lib/chat-instance-manager.ts第 26–29 行把 AI SDK 的Chat实例存放在模块级 Map中源码注释明确解释了动机Instances are scoped to an active chat route and removed on route teardown. This avoids accumulating background streams/message buffers when users switch between multiple chats quickly.——getOrCreateChatInstance(chatId, init)先查 Map命中则返回alreadyExisted: true复用既有实例未命中才new Chat(init)。如果把实例创建放进组件 effect快速切换聊天就会不断重建实例、泄漏后台流模块级状态让创建与组件挂载解耦。apps/web/lib/redis.ts第 3 行、127–136 行用const warnedMissingRedisFeatures new Setstring()实现同一功能的降级告警只打印一次warnRedisDisabled(feature)先查 Set已告警过的 feature 直接return。连console.error这种副作用都做了 once 语义去重是模块级守卫在日志侧的应用。组件内变体useRef 一次性守卫以及它的局限并非所有只初始化一次的逻辑都能上提到模块层。在 apps/web/app/sessions/[sessionId]/chats/[chatId]/session-chat-content.tsx 中客户端组件用 ref 实现了组件级一次性守卫第 2469 行声明、第 2486–2488 行使用const hasInitializedToolStatesRef useRef(false); // ... if (!hasInitializedToolStatesRef.current) { // 只执行一次的初始化逻辑 hasInitializedToolStatesRef.current true; }需要注意它与模块级守卫的本质区别ref 的状态挂在组件实例上只能保证同一次挂载内不重复执行组件一旦重挂载ref 归零、逻辑重跑。因此它只适合组件局部的一次性工作如工具状态的首帧初始化绝不能承担loadFromStorage()、checkAuthToken()这类应用级职责——那正是规则要禁止的用法。选型建议与适用边界结合规则原文与本仓库的实践可以归纳出如下决策路径初始化类型推荐位置仓库参照应用级一次性初始化SDK 注册、路由保护声明等入口模块顶层调用instrumentation-client.ts 中的initBotId(...)昂贵资源连接、客户端的懒创建模块级三态懒单例skills-cache.ts 的getSharedRedisClient()需要跨组件/跨挂载复用的实例模块级 Map 显式生命周期清理chat-instance-manager.ts 的chatInstances组件局部的一次性工作useRef布尔守卫session-chat-content.tsx的hasInitializedToolStatesRef重复触发会出错的 effecteffect 内加模块级didInit布尔守卫规则原文的 Correct 示例适用边界与限制即规则把影响定为 LOW-MEDIUM 的原因模块状态的生命周期是每次页面加载。生产环境模块代码每次加载执行一次但开发环境下 HMR 与整页刷新会重新执行模块模块变量随之重置。所以这条规则的主要价值正是其impactDescription所说的避免开发环境重复初始化而不是生产环境性能。模块级状态 ≠ 全局状态。从 chat-instance-manager.ts 的注释可见该团队对模块级 Map 中的实例在路由 teardown 时显式调用removeChatInstance(chatId)清理避免长期驻留的内存与流。把状态上提到模块层时应同步考虑谁负责释放。服务端与客户端的模块语义不同。instrumentation-client.ts的初始化针对客户端文件内注释明确为 client-side initialization而如 Redis 客户端这类服务端单例redis.ts 的createRedisClient在多请求共享进程的环境下被多个请求共用其once语义是跨请求的需要在设计中明确并发与失效策略。延伸阅读仓库内路径规则原文.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md规则集总览与分类.agents/skills/vercel-react-best-practices/SKILL.md、.agents/skills/vercel-react-best-practices/README.md同族进阶规则advanced-event-handler-refs.md、advanced-use-latest.md客户端入口初始化apps/web/instrumentation-client.ts、apps/web/instrumentation-client.test.ts模块级单例与共享状态apps/web/lib/skills-cache.ts、apps/web/lib/chat-instance-manager.ts、apps/web/lib/redis.ts组件内 ref 一次性守卫apps/web/app/sessions/[sessionId]/chats/[chatId]/session-chat-content.tsx【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 open-agents React 性能规则实战：应用级初始化只执行一次，而不是每次挂载都执行
open-agents React 性能规则实战应用级初始化只执行一次而不是每次挂载都执行【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents本篇基于 open-agents 仓库内置的 Vercel React 最佳实践规则集深入讲解advanced-init-once应用只初始化一次而非按组件挂载次数初始化这条规则先继承规则原文的反模式/正确模式对比再结合本仓库中instrumentation-client.ts、skills-cache.ts、chat-instance-manager.ts等真实源码拆解入口模块顶层初始化与模块级守卫两种落地形态的适用边界与注意事项。规则的来源与定位Vercel 最佳实践规则集中的 advanced-init-onceopen-agents 在 .agents/skills/vercel-react-best-practices/ 目录下内置了一套面向 Agent 与 LLM 结构化的 React/Next.js 性能规则库。根据 SKILL.md这套规则共 58 条、分 8 个类别按影响程度排序优先级类别影响文件前缀1消除串行等待WaterfallsCRITICALasync-2包体积优化CRITICALbundle-3服务端性能HIGHserver-4客户端数据获取MEDIUM-HIGHclient-5重渲染优化MEDIUMrerender-6渲染性能MEDIUMrendering-7JavaScript 性能LOW-MEDIUMjs-8高级模式Advanced PatternsLOWadvanced-本文的主题 advanced-init-once.md 属于第 8 类高级模式与advanced-event-handler-refs、advanced-use-latest并列。其 frontmatter 元信息为title: Initialize App Once, Not Per Mountimpact: LOW-MEDIUM —— 按 README.md 中影响等级定义属于低到中等收益其impactDescription明确写道avoids duplicate init in development避免在开发环境中重复初始化tags:initialization, useEffect, app-startup, side-effects该规则集对每条规则采用统一的结构frontmatter 元信息 规则说明 Incorrect 反例 Correct 正例 参考链接并通过pnpm build编译进 AGENTS.md。下面继承规则原文的核心内容再展开原理与仓库内的真实落地。规则核心不要将应用级初始化放进组件的 useEffect规则的原始表述是不要将必须每次应用加载只运行一次的应用级初始化放进组件的useEffect([])中。组件可能被重新挂载remount而 effect 会随之重新执行应改用模块级守卫module-level guard或在入口模块的顶层执行初始化。反模式开发模式下执行两次且组件重挂载时再次执行function Comp() { useEffect(() { loadFromStorage() checkAuthToken() }, []) // ... }正确写法每次应用加载只执行一次let didInit false function Comp() { useEffect(() { if (didInit) return didInit true loadFromStorage() checkAuthToken() }, []) // ... }两个要点值得展开为什么开发模式下执行两次React 在开发模式下StrictMode会对挂载 effect 做双重调用以暴露副作用代码中不可安全重放的问题。把 SDK 初始化、鉴权检查、本地存储读取这类一次性副作用写进useEffect([])在开发环境就会触发两次一旦组件因为路由切换、条件渲染、错误边界恢复等原因重新挂载effect 还会第三次、第四次执行。模块级守卫为什么有效didInit是挂在模块命名空间上的变量。组件卸载/重挂载不会重置模块状态因此守卫在整个页面生命周期内稳定。这也是规则把两种方案并列推荐的原因——模块级守卫是保守改法改动最小适合无法移动代码的场景而入口模块顶层初始化是更彻底的推荐改法模块代码在浏览器端每次页面加载只执行一次天然满足once per app load语义连 effect 都不需要。规则原文还指向了 React 官方文档《You Might Not Need an Effect》中的 Initializing the application 一节作为权威参考。open-agents 仓库中的真实落地三种只执行一次的形态本仓库在 Next.js App Router 架构下恰好完整覆盖了这条规则的三种落地形态下面逐一对照源码。形态一入口模块顶层初始化规则推荐的正解apps/web/instrumentation-client.ts 是客户端 instrumentation 入口文件其中 Vercel BotID 的客户端初始化直接写在模块顶层import { initBotId } from botid/client/core; export const botIdProtectedRoutes [ // AI text-generation endpoints { path: /api/chat, method: POST }, { path: /api/generate-pr, method: POST }, // ... ]; /** * Vercel BotID client-side initialization. * * Declares which routes require bot-detection challenge headers so the * server-side checkBotId() calls in each handler can verify the request. */ initBotId({ protect: botIdProtectedRoutes, });这里initBotId(...)的调用不依赖任何组件、任何 effect模块被加载的那一刻即客户端入口初始化阶段就完成注册天然满足每次应用加载只执行一次且与 UI 生命周期完全解耦。对应的 instrumentation-client.test.ts 直接import(./instrumentation-client)后断言botIdProtectedRoutes的内容验证了该入口模块可独立导入、无副作用泄漏的工程质量。这正是规则所倡导的top-level init in the entry module的直接实现。形态二模块级懒创建单例守卫比布尔量更强的守卫apps/web/lib/skills-cache.ts 展示了模块级守卫的进阶形态——三态懒单例第 27–41 行let sharedRedisClient: SkillsCacheRedisClient | null | undefined; function getSharedRedisClient(): SkillsCacheRedisClient | null { if (sharedRedisClient ! undefined) { return sharedRedisClient; } if (!isRedisConfigured()) { sharedRedisClient null; return sharedRedisClient; } sharedRedisClient createRedisClient(skills-cache); return sharedRedisClient; }这里用undefined / null / 客户端实例三个状态区分尚未尝试创建/已尝试但环境未配置 Redis永久失败无需重试/已成功创建。相比规则示例中的布尔didInit它把守卫从只执行一次扩展为只初始化一次 记住初始化结果首次调用getSharedRedisClient()时才真正创建 ioredis 客户端通过createRedisClient(skills-cache)后续调用直接复用未配置REDIS_URL/KV_URL时降级为内存缓存并记录一次错误日志。模块底部同样以const sharedSkillsCache createSkillsCache()第 267 行暴露全局单例缓存对外提供getCachedSkills/setCachedSkills。形态三模块级共享状态 一次性副作用去重同一条规则思想还体现在共享状态放在模块上、副作用只发生一次的工程约定中apps/web/lib/chat-instance-manager.ts第 26–29 行把 AI SDK 的Chat实例存放在模块级 Map中源码注释明确解释了动机Instances are scoped to an active chat route and removed on route teardown. This avoids accumulating background streams/message buffers when users switch between multiple chats quickly.——getOrCreateChatInstance(chatId, init)先查 Map命中则返回alreadyExisted: true复用既有实例未命中才new Chat(init)。如果把实例创建放进组件 effect快速切换聊天就会不断重建实例、泄漏后台流模块级状态让创建与组件挂载解耦。apps/web/lib/redis.ts第 3 行、127–136 行用const warnedMissingRedisFeatures new Setstring()实现同一功能的降级告警只打印一次warnRedisDisabled(feature)先查 Set已告警过的 feature 直接return。连console.error这种副作用都做了 once 语义去重是模块级守卫在日志侧的应用。组件内变体useRef 一次性守卫以及它的局限并非所有只初始化一次的逻辑都能上提到模块层。在 apps/web/app/sessions/[sessionId]/chats/[chatId]/session-chat-content.tsx 中客户端组件用 ref 实现了组件级一次性守卫第 2469 行声明、第 2486–2488 行使用const hasInitializedToolStatesRef useRef(false); // ... if (!hasInitializedToolStatesRef.current) { // 只执行一次的初始化逻辑 hasInitializedToolStatesRef.current true; }需要注意它与模块级守卫的本质区别ref 的状态挂在组件实例上只能保证同一次挂载内不重复执行组件一旦重挂载ref 归零、逻辑重跑。因此它只适合组件局部的一次性工作如工具状态的首帧初始化绝不能承担loadFromStorage()、checkAuthToken()这类应用级职责——那正是规则要禁止的用法。选型建议与适用边界结合规则原文与本仓库的实践可以归纳出如下决策路径初始化类型推荐位置仓库参照应用级一次性初始化SDK 注册、路由保护声明等入口模块顶层调用instrumentation-client.ts 中的initBotId(...)昂贵资源连接、客户端的懒创建模块级三态懒单例skills-cache.ts 的getSharedRedisClient()需要跨组件/跨挂载复用的实例模块级 Map 显式生命周期清理chat-instance-manager.ts 的chatInstances组件局部的一次性工作useRef布尔守卫session-chat-content.tsx的hasInitializedToolStatesRef重复触发会出错的 effecteffect 内加模块级didInit布尔守卫规则原文的 Correct 示例适用边界与限制即规则把影响定为 LOW-MEDIUM 的原因模块状态的生命周期是每次页面加载。生产环境模块代码每次加载执行一次但开发环境下 HMR 与整页刷新会重新执行模块模块变量随之重置。所以这条规则的主要价值正是其impactDescription所说的避免开发环境重复初始化而不是生产环境性能。模块级状态 ≠ 全局状态。从 chat-instance-manager.ts 的注释可见该团队对模块级 Map 中的实例在路由 teardown 时显式调用removeChatInstance(chatId)清理避免长期驻留的内存与流。把状态上提到模块层时应同步考虑谁负责释放。服务端与客户端的模块语义不同。instrumentation-client.ts的初始化针对客户端文件内注释明确为 client-side initialization而如 Redis 客户端这类服务端单例redis.ts 的createRedisClient在多请求共享进程的环境下被多个请求共用其once语义是跨请求的需要在设计中明确并发与失效策略。延伸阅读仓库内路径规则原文.agents/skills/vercel-react-best-practices/rules/advanced-init-once.md规则集总览与分类.agents/skills/vercel-react-best-practices/SKILL.md、.agents/skills/vercel-react-best-practices/README.md同族进阶规则advanced-event-handler-refs.md、advanced-use-latest.md客户端入口初始化apps/web/instrumentation-client.ts、apps/web/instrumentation-client.test.ts模块级单例与共享状态apps/web/lib/skills-cache.ts、apps/web/lib/chat-instance-manager.ts、apps/web/lib/redis.ts组件内 ref 一次性守卫apps/web/app/sessions/[sessionId]/chats/[chatId]/session-chat-content.tsx【免费下载链接】open-agentsAn open source template for building cloud agents.项目地址: https://gitcode.com/GitHub_Trending/op/open-agents创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考