前端调试手记：Stylus 栈溢出

调试的本质是验证假设，所有结论都要有证据。

这篇笔记整理一次真实的构建事故：一个 Vue 单文件组件内的 Stylus 样式过大，触发了 RangeError: Maximum call stack size exceeded。文章按调试的实际顺序记录：先刻画问题边界，再复盘诊断细节，最后补充常见陷阱和工具使用场景。

调试的起始清单

上线前后遇到异常，我会先确认以下三件事，确保所有讨论有共同的上下文：

系统边界：明确异常发生在客户端、服务端、构建阶段还是 CI/CD 流水线。不同边界对应不同的日志与工具。
复现路径：记录准确的操作步骤、输入参数、依赖版本，以及当前环境是否开启缓存或压缩。
判定标准：写下"什么结果算正确"。没有预期的对照，调试只会围着猜测打转。

做完这一步，后续的拆解才有清晰的方向。

案例背景

某次常规发布，CI 构建阶段（Node 18.19 + webpack 4 + stylus-loader）直接退出，日志只剩下如下堆栈：

RangeError: Maximum call stack size exceeded
    at Lexer.advance (/node_modules/stylus/lib/lexer.js:676:22)
    at Parser.parse (/node_modules/stylus/lib/parser.js:127:21)
    at Renderer.render (/node_modules/stylus/lib/renderer.js:97:18)

由于日志没有指向具体文件，调试工作从"定位罪魁祸首"开始。

1. 确认触发点

把 CI 中断的构建命令复制到本地执行，保持相同的 NODE_ENV、--mode 与 NODE_OPTIONS。定位到出错的是一个 1.6 MB 的 .vue 文件，Stylus 部分包含大量 mixin 嵌套和动态 @extend：

.chart-container
  padding 24px
  +grid-layout()
  for $type in $chart-types
    .item-{$type}
      +build-item($type)

单独执行 npx stylus --print file.styl 得到相同的栈溢出，说明问题与 webpack 无关，而是 Stylus 本身无法处理当前深度。

2. 缩小问题体积

把 Stylus 片段拆成多个文件，并在 .vue 文件中分段引入：

@import './chart/base'
@import './chart/variants'
@import './chart/states'

拆分后的每个 Stylus 文件控制在 300 KB 左右，本地构建恢复正常。这一步验证了"文件体积 + 递归深度"是真正的触发条件。

3. 查阅上游限制

Stylus 项目的 issue #2498 给出结论：Renderer 依赖 Node 的默认栈深度（约 984 KB），在大量递归调用时会触发溢出。官方没有计划修复，只建议通过 --stack_size 调整 Node 进程栈。

4. 选择最小改动方案

最终的调整分两步：

在构建脚本的入口增加显式栈大小：
```
node --stack_size=2048 scripts/build.js
```
把庞大的 Stylus 模块拆分成主题、状态、布局等几个子模块，把职责分界线写进代码评审规范，防止再次膨胀。

这一次的重点不在"换工具"，而在于确认哪个环节承担实际风险，并让结论可以复现。

缓存与交付环节的复核

构建类问题解决后，还需要验证上线路径是否存在隐藏的缓存和镜像：

浏览器缓存：调试接口时在 DevTools 勾选 Disable cache，或者附加 Cache-Control: no-store 响应头，避免旧资源干扰。
CDN/边缘节点：记录 x-cache、via、cf-cache-status 等头部，把命中情况写入日志。未命中时再回源比对内容摘要。
CI 产物缓存：禁止复用上一次构建的 node_modules/.cache 或输出目录；构建后计算关键文件 SHA-256，与部署机实际文件对比。
容器镜像：若部署使用镜像仓库，新增构建参数后务必修改标签，并在 Pod 内执行 sha256sum 复核。

缓存问题的典型误判是"我已经修好了，但线上还是老问题"。将指纹、版本号或 Git 提交信息输出到页面或接口响应里，是排查这类问题的快捷方式。

工具与使用时机

触发场景	建议工具	备注
函数调用路径不明	`debugger`、Chrome DevTools Call Stack	结合源码映射，确认实际执行分支
构建脚本异常	`node --inspect-brk`、VS Code 调试	断点调试 loader 和插件内部逻辑
资源加载缓慢	DevTools Performance 面板、Coverage	定位阻塞的脚本与未命中缓存的资源
CPU/内存异常	`0x`、`speedscope` 火焰图	对 Node 或浏览器进程采样，确认热点
网络响应异常	Charles/Fiddler、`curl -v`	保存请求过程，排除中间代理改写内容
复杂状态还原困难	DevTools Recorder、Playwright Trace Viewer	固化复现步骤，避免人肉重演

工具的选择不在于种类多，而是能否覆盖当前的验证需求。每次使用工具之前，先写下"需要确认的问题是什么"，再决定要捕获哪类数据。

性能侧的延伸检查

这次事故虽然发生在构建阶段，但同一套验证方法也适用于性能调优：

定义目标指标：明确 LCP、TTFB、Render Blocking Time 等指标的目标区间。
标记关键路径：通过 performance.mark、performance.measure 给主线程中的关键阶段打点。
分析阻塞点：使用火焰图观察函数栈高度，结合源码查找实际耗时逻辑（例如多余的深拷贝、未去抖的事件处理）。
验证优化效果：每次修改后重复采样，记录环境差异。数据没有显著改善，就不要合并。

性能调试与功能调试共享同一个原则：结论必须可复现、可回滚。

小结

调试前先定义边界、复现路径和成功标准，再进入细节。
遇到第三方工具的限制，先确认触发条件，再选择最小的改动方案（本例是增大 Node 栈并拆分 Stylus 模块）。
发布链路中所有缓存层级都要有验证手段，避免错把旧产物当成新结果。
工具的价值在于支撑假设检验，而不是盲目叠加配置。

把一次事故拆解成清晰的链路，可以直接复用于代码评审、发布 checklist 和团队文档。调试不是灵感，而是流程；流程越清楚，系统失控时恢复得越快。