LightningCSS项目构建时Docker环境下的调用栈溢出问题解析

问题现象

在使用LightningCSS（1.30.1版本）配合Astro（5.7版本）进行项目构建时，开发者在本地环境（Pop!_OS 22.04系统，Node.js v22.11.0，pnpm 10.10.0）能够顺利完成构建，但在Docker容器中却遭遇了"Maximum call stack size exceeded"（最大调用栈大小超出）的错误。

错误分析

从错误日志中可以观察到几个关键点：

1. 错误发生在Vite的依赖解析过程中
2. 调用栈显示findNearestPackageData和findNearestMainPackageData函数出现了无限递归
3. 问题在Node.js 22和24版本下都会重现
4. 错误与CSS处理无关，因为即使不使用CSS也会出现同样问题

根本原因

经过深入排查，发现问题根源在于Docker构建时的当前工作目录设置不当。原始Dockerfile中直接在根目录(/)下执行构建操作，这导致：

1. Vite在解析依赖时会递归查找package.json文件
2. 从根目录开始查找会遍历整个文件系统
3. Docker镜像的根目录包含大量系统文件和目录
4. 这种大规模递归查找最终耗尽了JavaScript调用栈

解决方案

通过在Dockerfile中明确指定工作目录即可解决此问题：

FROM node:22-bookworm AS build

# 关键修复：设置专门的工作目录
WORKDIR /app
COPY . .

RUN npm install -g pnpm
RUN pnpm install
RUN pnpm build

技术原理详解

这个问题的本质是Node.js模块解析机制与Docker环境特性的冲突：

1. Node.js模块解析：Vite在构建时会通过findNearestPackageData向上递归查找package.json文件，这是Node.js模块系统的标准行为。

2. Docker文件系统特性：容器内的根目录包含完整的Linux文件系统结构，包括/bin、/etc、/var等众多目录。

3. 递归深度问题：当从根目录开始递归查找时，系统会遍历所有子目录，导致递归深度过大。

4. 调用栈限制：JavaScript引擎对调用栈深度有严格限制（通常约1万层左右），超出就会抛出调用栈溢出错误。

最佳实践建议

1. 明确工作目录：在Dockerfile中始终使用WORKDIR指令指定明确的工作目录。

2. 最小化构建上下文：通过.dockerignore文件排除不必要的文件和目录。

3. 分层构建：合理利用Docker的构建缓存，将依赖安装与源代码复制分开。

4. 环境一致性：确保开发环境与构建环境的关键配置一致。

5. 错误诊断：遇到类似递归问题时，首先检查工作目录和文件系统结构。

总结

这个问题展示了环境配置对构建过程的重要影响。通过理解Node.js模块解析机制和Docker文件系统特点，我们能够有效避免这类"Maximum call stack size exceeded"错误。关键在于为构建过程创建一个干净、隔离的工作环境，避免不必要的文件系统遍历。