Infinite Canvas 前端条件加载实践：按需加载模块优化 React 应用包体与 SSR 构建

• AI 应用
• 媒体生成
• 前端
• AI Agent
• AI 技能

导读

本篇技术指南围绕.agents/skills/vercel-react-best-practices/rules/bundle-conditional.md中定义的Conditional Module Loading（条件模块加载）规则展开，讲解如何在 React/Next.js 应用中"只有功能被激活时才加载大数据或大模块"。你会掌握基于功能开关的懒加载写法、typeof window !== 'undefined'在 SSR 场景下的作用与原理，以及错误降级处理；同时结合 Infinite Canvas（AI 创作无限画布工作台）开源仓库中的真实源码，看到同样的模式如何在图片生成、画布插件、素材清理等实际功能中被落地应用。

规则背景：Bundle Size Optimization 体系中的条件加载

在 Infinite Canvas 仓库的.agents/skills/vercel-react-best-practices/技能包中，性能优化规则按优先级被划分为 8 大类，其中Bundle Size Optimization（包体优化）位列第 2 优先级、影响等级为 CRITICAL，全部以bundle-前缀命名（见 SKILL.md 的规则分类表）。条件模块加载（bundle-conditional）是这一体系中的重要成员，与之同组的规则还包括：

• bundle-dynamic-imports：对首屏不需要的重组件使用next/dynamic懒加载；
• bundle-defer-third-party：把分析、日志等第三方库推迟到水合之后加载；
• bundle-preload：在 hover/focus 时预加载，提升感知速度；
• bundle-barrel-imports：避免 barrel 文件造成的冗余打包。

条件模块加载与前两者互补：bundle-dynamic-imports关注"何时渲染"，bundle-defer-third-party关注"何时水合"，而bundle-conditional关注"功能是否开启"——只有当某个功能真正被激活时，才去加载对应的数据或模块。

规则核心：仅在功能激活时加载模块

规则原文（bundle-conditional.md）给出的核心主张是：

Load large data or modules only when a feature is activated. （仅在功能被激活时才加载大数据或大模块。）

其典型示例是一个"动画播放器"组件：动画帧数据体积大、初始无意义，只有用户开启动画后才值得下载。

function AnimationPlayer({ enabled, setEnabled }: { enabled: boolean; setEnabled: React.Dispatch<React.SetStateAction<boolean>> }) { const [frames, setFrames] = useState<Frame[] | null>(null) useEffect(() => { if (enabled && !frames && typeof window !== 'undefined') { import('./animation-frames.js') .then(mod => setFrames(mod.frames)) .catch(() => setEnabled(false)) } }, [enabled, frames, setEnabled]) if (!frames) return <Skeleton /> return <Canvas frames={frames} /> }

逐段拆解这个示例

1. 状态建模：frames初始为null，既是数据容器又是加载状态指示器；null表示"尚未加载"，可直接渲染<Skeleton />占位，无需单独的loading标志位。
2. 触发条件：useEffect依赖[enabled, frames, setEnabled]。只有enabled为真、且frames仍为null（避免重复加载）时，才发起动态import()。
3. 异步加载与错误降级：.then(mod => setFrames(mod.frames))把模块的导出写入状态；.catch(() => setEnabled(false))在加载失败时自动关闭功能开关，让 UI 回到未启用状态而不是一直卡在加载中——这是条件加载模式中容易被忽略、但实战价值极高的容错设计。
4. SSR 隔离：typeof window !== 'undefined'确保该模块不会被打包进服务端渲染（SSR）产物。

typeof window !== 'undefined'的作用与原理

规则明确指出：

Thetypeof window !== 'undefined'check prevents bundling this module for SSR, optimizing server bundle size and build speed. （typeof window !== 'undefined'检查可防止该模块被打包进 SSR，优化服务端包体大小与构建速度。）

这里需要解释清楚一个容易混淆的点：typeof window !== 'undefined'并不是运行时才生效的"条件守卫"，它的真正价值在于告知打包器这是一个浏览器专用模块。以 Next.js / Vercel 生态为例：

• 当打包器（webpack 等）在构建 SSR 产物时遇到import('./animation-frames.js')，会同时分析代码中typeof window的检查；
• 由于服务端环境没有window，打包器可以在编译期静态推导出该分支在服务端不可达，从而把整个import()对应的 chunk 从服务端产物中排除；
• 结果就是服务端 bundle 更小、构建更快，同时浏览器端仍能按需加载该模块。

同理，同技能包中的bundle-dynamic-imports规则（bundle-dynamic-imports.md）展示了配套写法：对 Monaco 这类重型编辑器，用next/dynamic的{ ssr: false }选项显式声明"仅客户端渲染"，避免主 bundle 被塞入数百 KB 的编辑器代码：

import dynamic from 'next/dynamic' const MonacoEditor = dynamic( () => import('./monaco-editor').then(m => m.MonacoEditor), { ssr: false } ) function CodePanel({ code }: { code: string }) { return <MonacoEditor value={code} /> }

两个规则可以组合使用：dynamic()负责组件级懒加载与 SSR 排除，enabled &&条件负责功能级激活判断。

Infinite Canvas 仓库中的真实落地

条件加载模式在 Infinite Canvas 的前端（web/）中并非理论，而是已有多处实践。下面结合源码逐一说明。

1. 图片生成：操作时才加载图片存储服务

在 canvas-node-generation.ts 中，生成节点上下文的水合（hydrate）过程只有在真正需要把参考图转为 Data URL 时才动态引入图片存储模块：

export async function hydrateNodeGenerationContext(context: NodeGenerationContext) { const { imageToDataUrl } = await import("@/services/image-storage"); return { ...context, referenceImages: await Promise.all(context.referenceImages.map(async (image) => ({ ...image, dataUrl: await imageToDataUrl(image) }))) }; }

@/services/image-storage负责从本地存储中还原图片数据，属于"发起 AI 生成请求前才需要"的重操作。将它放在await import()中，意味着普通画布浏览、编辑操作不会加载该模块，只有真正触发生成流程的调用路径才会拉取对应 chunk。

2. 画布插件：运行时按需加载第三方插件代码

条件加载最典型的场景是插件系统。plugin-loader.ts 用 Blob URL 配合动态 import 实现远程插件的按需求值：

async function evaluatePluginSource(source: string): Promise<CanvasPlugin> { const blob = new Blob([source], { type: "text/javascript" }); const url = URL.createObjectURL(blob); try { const mod = (await import(/* @vite-ignore */ url)) as { default?: unknown; plugin?: unknown }; const exported = mod.default ?? mod.plugin; const plugin = typeof exported === "function" ? (exported as (runtime: unknown) => unknown)(getPluginRuntime()) : exported; assertPlugin(plugin); return plugin; } finally { URL.revokeObjectURL(url); } }

这里体现了条件加载的两层含义：

• 功能层：插件安装/启用前（installPluginFromUrl、setPluginEnabled、ensurePluginsLoaded等入口），其代码不会被解析执行；setPluginEnabled(record, false)时通过deactivatePlugin卸载（见 plugin-loader.ts），实现"启用才加载、停用即释放"；
• 打包层：/* @vite-ignore */注释让 Vite 不对运行时 URL 做静态分析与打包，避免把动态获取的插件源码错误地打进主 bundle——与规则中"功能未激活时不打包"的意图一致。

3. 素材清理：延迟到空闲时再加载画布 Store

在 use-asset-store.ts 中，清理未使用图片/媒体的逻辑被推迟到setTimeout(0)之后的空闲时机，且清理函数内部才动态引入画布 Store：

cleanupImages: (extra) => { window.setTimeout(async () => { const { useCanvasStore } = await import("@/stores/canvas/use-canvas-store"); await cleanupUnusedImages({ assets: get().assets, projects: useCanvasStore.getState().projects, extra }); await cleanupUnusedMedia({ assets: get().assets, projects: useCanvasStore.getState().projects, extra }); }, 0); },

素材删除并不是每次删除操作都立即需要画布工程数据，因此把use-canvas-store的加载推迟到清理真正执行的那一刻，既减小了素材管理模块的初始依赖面，也避免了与主流程争抢首屏资源。

条件加载的完整落地清单

综合规则文件与仓库实践，落地条件加载时可以对照以下清单：

1. 识别"重而低频"的模块：优先处理动画帧、编辑器、存储层、插件运行时这类体积大、且仅在特定功能开启时才使用的模块。
2. 用状态表达"未加载"：如frames === null，让占位 UI（<Skeleton />）与真实内容共用同一状态，避免多余 loading 标志。
3. 把激活条件写进 effect 依赖：[enabled, frames, setEnabled]确保条件变化时重新评估，且已加载后不再重复拉取。
4. 处理失败降级：.catch(() => setEnabled(false))让加载失败自动回退到功能关闭态，而不是永久卡在加载中。
5. SSR 隔离：typeof window !== 'undefined'或next/dynamic的{ ssr: false }，确保浏览器专用模块不进服务端产物。
6. 静态可分析：尽量使用字面量路径（如'./animation-frames.js'、"@/services/image-storage"），避免动态拼接字符串导致打包器无法分 chunk；对确需运行时 URL 的插件加载，使用/* @vite-ignore */明确告知构建工具。

总结

条件模块加载（bundle-conditional）是 React/Next.js 包体优化的关键一环：它把"加载时机"从渲染期提前绑定到"功能激活事件"，配合typeof window !== 'undefined'的 SSR 隔离和.catch()降级处理，能够在功能未开启时不下载、服务端不打包、失败时不崩溃。在 Infinite Canvas 仓库中，从 AI 生成水合、画布插件系统到素材清理，都能看到这一模式的实际应用，可作为读者在自己项目中迁移落地的直接参考。

相关阅读：完整规则体系见 .agents/skills/vercel-react-best-practices/README.md 与 SKILL.md；组件级懒加载见 bundle-dynamic-imports.md；第三方库延迟加载见 bundle-defer-third-party.md。

• AI 应用
• 媒体生成
• 前端
• AI Agent
• AI 技能