Windmill 前端 chunk 循环依赖Chunk Cycle排查实战从 500 崩溃到构建期拦截【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill在大型 SvelteKit 应用中模块依赖无环acyclic并不等于打包产物无环——Vite/Rollup 对 chunk 的分组grouping本身就可能凭空造出循环导致应用加载即崩溃且服务端日志为空。本文以 Windmill 开源仓库的 docs/frontend-import-cycles.md 为骨架结合 frontend/vite.config.js 中的构建期校验插件、advancedChunks分组修复与loadCopilot提取重构的真实案例系统讲解 chunk 循环的成因、症状、定位方法与修复策略。读完本文你将掌握为什么TypeError: be is not a constructor这类报错是循环 chunk 的典型信号、如何读懂构建失败的循环报告、以及用import type、advancedChunks分组和模块拆分三种手段切断循环的完整思路。症状加载即崩溃但服务端一无所知当打包产物中的 chunk 相互循环引用时应用会在加载阶段直接崩溃报错形如TypeError: be is not a constructor Cannot read properties of undefined (reading PREPROCESSOR)此时用户看到的是 SvelteKit 默认的500 / Internal Error页面而服务端日志里什么都没有——因为崩溃发生在浏览器端模块求值阶段不是一次 HTTP 请求失败。这类错误极具迷惑性与路由相关哪个成员先求值取决于哪个路由先把循环中的 chunk 拉进页面因此同一份产物在不同路由上表现不同看起来随机第二次刷新页面可能就好了不是缓存或资源过期问题重新构建后资源哈希asset hash变了但依赖图没有变崩溃依旧。Windmill 前端对此的最终防线是构建期拦截assertAcyclicChunks插件挂在 frontend/vite.config.js 的generateBundle钩子上一旦检测到 chunk 之间存在环就直接让vite build失败从源头杜绝这类运行时崩溃进入生产环境。该插件的核心逻辑是收集每个 chunk 的imports列表构建 chunk 级依赖图用 DFS深度优先遍历借助visiting/done两态标记在图中找环找到环后调用this.error(...)中止构建并输出完整的环路径见下文读懂构建失败报告一节。因此本文讨论的场景主要出现在构建期报错而不再是线上偶发崩溃。为什么 chunk 循环会崩溃模块求值语义要理解崩溃机理必须先回到 ES module 的求值规则一个 chunk 的所有 import 会先于它自身的函数体被求值。当 chunk A 与 chunk B 互相 import 时从 A 进入加载流程意味着先求值 B 的主体而此时 A 的任何代码都还没有执行。于是 B 从 A 读取的每一个绑定都停留在未初始化状态但不同类型的绑定表现截然不同绑定形式未初始化时的表现function f() {}函数声明会被提升hoisted此时调用它反而能正常工作var X class {}变量提升但值为undefinednew X()直接抛X is not a constructorconst X {...}完全未初始化TDZ读取即抛Cannot read properties of undefined典型的死亡组合是B 的模块级代码调用了一个看起来正常的 hoisted 函数而该函数内部去读取 A 中尚未初始化的 class 或 const于是崩溃在运行到一半的求值过程中。文档中给出的两个高危示例const toolDef createToolDef(schema, x, ...) // 内部调用 z.toJSONSchema - new JSONSchemaGenerator const ids { a: SPECIAL_MODULE_IDS.PREPROCESSOR } // 读取一个被 import 进来的 const这类模块求值期module-scope的副作用只要依赖跨 chunk 成环每一个都是独立的地雷。关键认知是逐个把模块级读取改成惰性lazy是治标不治本——循环中的每一处模块级读取都是独立隐患下一次重构又会冒出新的一处。正确的做法只有一个切断循环。一个无环的模块图也可能产出循环的 chunk 图这是本文最容易被忽视、也最值得记住的一点chunk 分组本身就能制造循环即使模块之间并不存在 import 环。Windmill 在 Vite 8.2.0对应 issue #10468上就真实踩中了这个坑。事故的主角是src/lib/gen——一个自包含的生成式 API 客户端由openapi-ts从后端 OpenAPI 规范生成参见 frontend/package.json 中的generate-backend-client脚本openapi-ts --input ../backend/windmill-api/openapi.yaml --output ./src/lib/gen。从模块依赖看它不 import 任何外部模块是一个典型的叶子模块leafindex.ts与core/*被打进一个 chunk而长达约 12000 行的schemas.gen.ts被分到另一个 chunk与53 个无关的 copilot/app 模块混在一起。问题就出在index.ts里的barrel 文件桶文件写法——export * from ./schemas.gen。这个 re-export 让genchunk 拥有了指向那个app 混合 chunk的边而该 app chunk 中的 copilot 工具模块又会反向 import 回 copilot core chunk……一次分组直接产生了 40 个 chunk 循环。后果是 copilot 的工具模块在模块作用域调用createToolDef时撞上未初始化的 zodJSONSchemaGenerator这正是上文be is not a constructor一类报错的来源。修复方式是把这颗叶子完整地保持在一个 chunk 里在 frontend/vite.config.js 中通过advancedChunks.groups实现build: { rollupOptions: { output: { advancedChunks: { groups: [{ name: gen, test: /[\\/]src[\\/]lib[\\/]gen[\\/]/ }] } } } }这段配置告诉 bundler凡是路径匹配src/lib/gen/的模块全部归入名为gen的独立 chunk不再与 app 代码混编。src/lib/gen目录本身是构建期由openapi-ts生成到frontend/src/lib/gen/下的frontend/AGENTS.md中将其列为Backend API routes 对应的生成类型因此整个前端大量组件如 AIAgentLogViewer.svelte、ApiConnectForm.svelte 等都会从$lib/gen导入类型与 API 服务类。值得警惕的形状一个 barrel 文件export * from ...罩着一个大型生成模块。它会给 barrel 的每一个 import 者都加上一条指向被 re-export 模块的依赖边而这条边最终落在哪个 chunk 里完全由 bundler 决定——这正是 chunk 图与模块图发生背离的温床。构建失败时如何读懂报告并定位源头一旦assertAcyclicChunks触发构建失败信息会打印出循环的完整链路并附上每个 chunk 的部分源码模块列表最多展示 6 个其余以N more汇总格式如下Cyclic chunk imports — this ships a runtime crash: _app/immutable/chunks/BdWm9WXx.js lib/gen/core/ApiError.ts, ..., lib/gen/index.ts - _app/immutable/chunks/BUOJL1Np.js lib/gen/schemas.gen.ts, lib/components/copilot/chat/workspaceTools.ts, 42 more - ...阅读方式chunk 1 中有某个模块 import 了 chunk 2 中的某个模块chunk 2 又 import 了 chunk 3……如此循环回到 chunk 1。逐环走完报告后找到环上相邻两个 chunk 之间真正的源码级 import 边——即在 chunk N 中、import 了 chunk N1 中模块的那个文件。这就是罪魁祸首边offending edge。这一步不需要猜测报告已经列出了每个 chunk 的成员模块对照相邻两行的模块列表求交集即可。三种修复手段按优先级定位到 offending edge 后按以下优先级依次尝试1. 只导入类型把 import 改成 type-only如果两个模块之间只用到了对方的类型interface、type alias 等就把导入改成import type形式。import type在编译期被完全擦除不产生任何运行时依赖边。等价的做法还包括命名导入中所有绑定都以type前缀标记import { type Foo } from ...用await import()动态导入——它会延迟到独立的求值时机不参与模块级求值循环。这是成本最低、最安全的修复适用于一切只是为了类型的跨模块引用。2. 用advancedChunks分组保住叶子模块适用于文档中src/lib/gen的场景一个自包含、无外部依赖的叶子模块被 bundler 拆散。此时用上文的分组配置把整个叶子目录钉进同一个 chunk从 chunk 层面消除它与其他 app chunk 的混编。3. 把罪魁函数移到新模块让低层模块停止 import 高层模块适用于真正的模块级循环。Windmill 的实战案例在aiStore与 copilot 客户端之间lib/aiStore.tsAI 模型状态为了loadCopilot中的一次调用import 了components/copilot/lib.tsAI 客户端而该客户端又 import 回 chat 相关模块chat 模块反过来 importaiStore——环由此而生。修复是在 frontend/src/lib/components/copilot/loadCopilot.ts 中新建独立模块把loadCopilot提取进去。该文件头部注释明确记录了这次重构的动机Lives here, not in$lib/aiStore, purely so that module needs no import of the AI client——moving it back recreates theaiStore - copilot/lib - copilot/chat/shared - aiStorecycle放在这里纯粹是为了让aiStore不再 import AI 客户端移回去就会重现上述循环。提取之后aiStore变成叶子它的 import 列表只剩svelte/store、./gen类型、./stores、./utils与reasoningRegistry且其中 AI 相关类型全部走import type见 frontend/src/lib/aiStore.ts 顶部Keep this module a leaf的注释约定依赖方向变为单向loadCopilot.ts - aiStoreloadCopilot.ts - copilot/lib而copilot/chat - loadCopilot不再触及aiStore。这种依赖倒置 独立模块的手法比任何惰性化改造都更彻底——它从依赖图上删掉了那条边而不是在求值时序上打补丁。无正确路由时如何复现崩溃由于崩溃取决于哪个路由先进入循环靠人工点击页面可能永远复现不出来。文档给出了一种强制复现的可靠方法执行vite build构建产物用静态服务托管build/目录例如vite preview对应 frontend/vite.config.js 中的preview: { port: 3001 }在一个页面里动态 import 持有共享绑定的那个 chunk——只要它身处循环import就会抛出与用户报告完全相同的错误。script typemodule try { await import(/_app/immutable/chunks/shared-chunk.js) document.title OK } catch (e) { document.title THREW: e.message } /script页面标题会直接显示OK或THREW: ...把真实的错误消息暴露出来便于与用户上报的报错比对。如何从几十个 hash 命名的 chunk 里找到目标利用 minification 也会保留的字符串字面量——例如 zod 的报错文案Error converting schema to JSON.在产物目录里搜到这个字符串就能定位到持有JSONSchemaGenerator的那个 chunk。核心要点回顾chunk 循环的崩溃根因是求值顺序循环成员在对方尚未初始化的状态下被求值hoisted 函数与未初始化 class/const 的组合制造出诡异的is not a constructor类报错且表现随路由而变、看似随机。模块图无环 ≠ chunk 图无环export * from的 barrel 文件 大生成模块 bundler 分组可能一次分裂出几十个 chunk 级循环Windmill 的真实事故为 40 个。构建期拦截是底线assertAcyclicChunksfrontend/vite.config.js在generateBundle阶段做 DFS 环检测让这类崩溃无法再进入生产。修复优先级import type擦除运行时边 →advancedChunks.groups保住叶子模块 → 提取函数到新模块切断模块级循环而不是逐个把模块级读取改成惰性。复现与定位构建产物 动态 import 目标 chunk 可强制触发崩溃用保留的字符串字面量在产物中反查 chunk 归属。对于任何以 SvelteKit/Vite 构建、包含大型生成客户端代码与复杂功能模块的前端工程把上述构建期环检测 叶子分组 模块级拆边的组合拳沉淀为工程规范就能在 chunk 循环问题上一劳永逸——这正是 Windmill 前端从一次 40 个 chunk 循环的事故中提炼出的完整实践。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Windmill 前端 chunk 循环依赖（Chunk Cycle）排查实战：从 500 崩溃到构建期拦截
Windmill 前端 chunk 循环依赖Chunk Cycle排查实战从 500 崩溃到构建期拦截【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill在大型 SvelteKit 应用中模块依赖无环acyclic并不等于打包产物无环——Vite/Rollup 对 chunk 的分组grouping本身就可能凭空造出循环导致应用加载即崩溃且服务端日志为空。本文以 Windmill 开源仓库的 docs/frontend-import-cycles.md 为骨架结合 frontend/vite.config.js 中的构建期校验插件、advancedChunks分组修复与loadCopilot提取重构的真实案例系统讲解 chunk 循环的成因、症状、定位方法与修复策略。读完本文你将掌握为什么TypeError: be is not a constructor这类报错是循环 chunk 的典型信号、如何读懂构建失败的循环报告、以及用import type、advancedChunks分组和模块拆分三种手段切断循环的完整思路。症状加载即崩溃但服务端一无所知当打包产物中的 chunk 相互循环引用时应用会在加载阶段直接崩溃报错形如TypeError: be is not a constructor Cannot read properties of undefined (reading PREPROCESSOR)此时用户看到的是 SvelteKit 默认的500 / Internal Error页面而服务端日志里什么都没有——因为崩溃发生在浏览器端模块求值阶段不是一次 HTTP 请求失败。这类错误极具迷惑性与路由相关哪个成员先求值取决于哪个路由先把循环中的 chunk 拉进页面因此同一份产物在不同路由上表现不同看起来随机第二次刷新页面可能就好了不是缓存或资源过期问题重新构建后资源哈希asset hash变了但依赖图没有变崩溃依旧。Windmill 前端对此的最终防线是构建期拦截assertAcyclicChunks插件挂在 frontend/vite.config.js 的generateBundle钩子上一旦检测到 chunk 之间存在环就直接让vite build失败从源头杜绝这类运行时崩溃进入生产环境。该插件的核心逻辑是收集每个 chunk 的imports列表构建 chunk 级依赖图用 DFS深度优先遍历借助visiting/done两态标记在图中找环找到环后调用this.error(...)中止构建并输出完整的环路径见下文读懂构建失败报告一节。因此本文讨论的场景主要出现在构建期报错而不再是线上偶发崩溃。为什么 chunk 循环会崩溃模块求值语义要理解崩溃机理必须先回到 ES module 的求值规则一个 chunk 的所有 import 会先于它自身的函数体被求值。当 chunk A 与 chunk B 互相 import 时从 A 进入加载流程意味着先求值 B 的主体而此时 A 的任何代码都还没有执行。于是 B 从 A 读取的每一个绑定都停留在未初始化状态但不同类型的绑定表现截然不同绑定形式未初始化时的表现function f() {}函数声明会被提升hoisted此时调用它反而能正常工作var X class {}变量提升但值为undefinednew X()直接抛X is not a constructorconst X {...}完全未初始化TDZ读取即抛Cannot read properties of undefined典型的死亡组合是B 的模块级代码调用了一个看起来正常的 hoisted 函数而该函数内部去读取 A 中尚未初始化的 class 或 const于是崩溃在运行到一半的求值过程中。文档中给出的两个高危示例const toolDef createToolDef(schema, x, ...) // 内部调用 z.toJSONSchema - new JSONSchemaGenerator const ids { a: SPECIAL_MODULE_IDS.PREPROCESSOR } // 读取一个被 import 进来的 const这类模块求值期module-scope的副作用只要依赖跨 chunk 成环每一个都是独立的地雷。关键认知是逐个把模块级读取改成惰性lazy是治标不治本——循环中的每一处模块级读取都是独立隐患下一次重构又会冒出新的一处。正确的做法只有一个切断循环。一个无环的模块图也可能产出循环的 chunk 图这是本文最容易被忽视、也最值得记住的一点chunk 分组本身就能制造循环即使模块之间并不存在 import 环。Windmill 在 Vite 8.2.0对应 issue #10468上就真实踩中了这个坑。事故的主角是src/lib/gen——一个自包含的生成式 API 客户端由openapi-ts从后端 OpenAPI 规范生成参见 frontend/package.json 中的generate-backend-client脚本openapi-ts --input ../backend/windmill-api/openapi.yaml --output ./src/lib/gen。从模块依赖看它不 import 任何外部模块是一个典型的叶子模块leafindex.ts与core/*被打进一个 chunk而长达约 12000 行的schemas.gen.ts被分到另一个 chunk与53 个无关的 copilot/app 模块混在一起。问题就出在index.ts里的barrel 文件桶文件写法——export * from ./schemas.gen。这个 re-export 让genchunk 拥有了指向那个app 混合 chunk的边而该 app chunk 中的 copilot 工具模块又会反向 import 回 copilot core chunk……一次分组直接产生了 40 个 chunk 循环。后果是 copilot 的工具模块在模块作用域调用createToolDef时撞上未初始化的 zodJSONSchemaGenerator这正是上文be is not a constructor一类报错的来源。修复方式是把这颗叶子完整地保持在一个 chunk 里在 frontend/vite.config.js 中通过advancedChunks.groups实现build: { rollupOptions: { output: { advancedChunks: { groups: [{ name: gen, test: /[\\/]src[\\/]lib[\\/]gen[\\/]/ }] } } } }这段配置告诉 bundler凡是路径匹配src/lib/gen/的模块全部归入名为gen的独立 chunk不再与 app 代码混编。src/lib/gen目录本身是构建期由openapi-ts生成到frontend/src/lib/gen/下的frontend/AGENTS.md中将其列为Backend API routes 对应的生成类型因此整个前端大量组件如 AIAgentLogViewer.svelte、ApiConnectForm.svelte 等都会从$lib/gen导入类型与 API 服务类。值得警惕的形状一个 barrel 文件export * from ...罩着一个大型生成模块。它会给 barrel 的每一个 import 者都加上一条指向被 re-export 模块的依赖边而这条边最终落在哪个 chunk 里完全由 bundler 决定——这正是 chunk 图与模块图发生背离的温床。构建失败时如何读懂报告并定位源头一旦assertAcyclicChunks触发构建失败信息会打印出循环的完整链路并附上每个 chunk 的部分源码模块列表最多展示 6 个其余以N more汇总格式如下Cyclic chunk imports — this ships a runtime crash: _app/immutable/chunks/BdWm9WXx.js lib/gen/core/ApiError.ts, ..., lib/gen/index.ts - _app/immutable/chunks/BUOJL1Np.js lib/gen/schemas.gen.ts, lib/components/copilot/chat/workspaceTools.ts, 42 more - ...阅读方式chunk 1 中有某个模块 import 了 chunk 2 中的某个模块chunk 2 又 import 了 chunk 3……如此循环回到 chunk 1。逐环走完报告后找到环上相邻两个 chunk 之间真正的源码级 import 边——即在 chunk N 中、import 了 chunk N1 中模块的那个文件。这就是罪魁祸首边offending edge。这一步不需要猜测报告已经列出了每个 chunk 的成员模块对照相邻两行的模块列表求交集即可。三种修复手段按优先级定位到 offending edge 后按以下优先级依次尝试1. 只导入类型把 import 改成 type-only如果两个模块之间只用到了对方的类型interface、type alias 等就把导入改成import type形式。import type在编译期被完全擦除不产生任何运行时依赖边。等价的做法还包括命名导入中所有绑定都以type前缀标记import { type Foo } from ...用await import()动态导入——它会延迟到独立的求值时机不参与模块级求值循环。这是成本最低、最安全的修复适用于一切只是为了类型的跨模块引用。2. 用advancedChunks分组保住叶子模块适用于文档中src/lib/gen的场景一个自包含、无外部依赖的叶子模块被 bundler 拆散。此时用上文的分组配置把整个叶子目录钉进同一个 chunk从 chunk 层面消除它与其他 app chunk 的混编。3. 把罪魁函数移到新模块让低层模块停止 import 高层模块适用于真正的模块级循环。Windmill 的实战案例在aiStore与 copilot 客户端之间lib/aiStore.tsAI 模型状态为了loadCopilot中的一次调用import 了components/copilot/lib.tsAI 客户端而该客户端又 import 回 chat 相关模块chat 模块反过来 importaiStore——环由此而生。修复是在 frontend/src/lib/components/copilot/loadCopilot.ts 中新建独立模块把loadCopilot提取进去。该文件头部注释明确记录了这次重构的动机Lives here, not in$lib/aiStore, purely so that module needs no import of the AI client——moving it back recreates theaiStore - copilot/lib - copilot/chat/shared - aiStorecycle放在这里纯粹是为了让aiStore不再 import AI 客户端移回去就会重现上述循环。提取之后aiStore变成叶子它的 import 列表只剩svelte/store、./gen类型、./stores、./utils与reasoningRegistry且其中 AI 相关类型全部走import type见 frontend/src/lib/aiStore.ts 顶部Keep this module a leaf的注释约定依赖方向变为单向loadCopilot.ts - aiStoreloadCopilot.ts - copilot/lib而copilot/chat - loadCopilot不再触及aiStore。这种依赖倒置 独立模块的手法比任何惰性化改造都更彻底——它从依赖图上删掉了那条边而不是在求值时序上打补丁。无正确路由时如何复现崩溃由于崩溃取决于哪个路由先进入循环靠人工点击页面可能永远复现不出来。文档给出了一种强制复现的可靠方法执行vite build构建产物用静态服务托管build/目录例如vite preview对应 frontend/vite.config.js 中的preview: { port: 3001 }在一个页面里动态 import 持有共享绑定的那个 chunk——只要它身处循环import就会抛出与用户报告完全相同的错误。script typemodule try { await import(/_app/immutable/chunks/shared-chunk.js) document.title OK } catch (e) { document.title THREW: e.message } /script页面标题会直接显示OK或THREW: ...把真实的错误消息暴露出来便于与用户上报的报错比对。如何从几十个 hash 命名的 chunk 里找到目标利用 minification 也会保留的字符串字面量——例如 zod 的报错文案Error converting schema to JSON.在产物目录里搜到这个字符串就能定位到持有JSONSchemaGenerator的那个 chunk。核心要点回顾chunk 循环的崩溃根因是求值顺序循环成员在对方尚未初始化的状态下被求值hoisted 函数与未初始化 class/const 的组合制造出诡异的is not a constructor类报错且表现随路由而变、看似随机。模块图无环 ≠ chunk 图无环export * from的 barrel 文件 大生成模块 bundler 分组可能一次分裂出几十个 chunk 级循环Windmill 的真实事故为 40 个。构建期拦截是底线assertAcyclicChunksfrontend/vite.config.js在generateBundle阶段做 DFS 环检测让这类崩溃无法再进入生产。修复优先级import type擦除运行时边 →advancedChunks.groups保住叶子模块 → 提取函数到新模块切断模块级循环而不是逐个把模块级读取改成惰性。复现与定位构建产物 动态 import 目标 chunk 可强制触发崩溃用保留的字符串字面量在产物中反查 chunk 归属。对于任何以 SvelteKit/Vite 构建、包含大型生成客户端代码与复杂功能模块的前端工程把上述构建期环检测 叶子分组 模块级拆边的组合拳沉淀为工程规范就能在 chunk 循环问题上一劳永逸——这正是 Windmill 前端从一次 40 个 chunk 循环的事故中提炼出的完整实践。【免费下载链接】windmillOpen-source developer platform to power your entire infra and turn scripts into webhooks, workflows and UIs. Fastest workflow engine (13x vs Airflow). Open-source alternative to Retool and Temporal.项目地址: https://gitcode.com/GitHub_Trending/wi/windmill创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考