背景场景
在 WSL2 的 Ubuntu 子系统中运行 Turborepo Monorepo 项目(Next.js 16 + React 19 + pnpm workspace),使用 pnpm dev 同时启动 5 个应用(web、admin、content-admin、blog、docs)时,WSL2 频繁崩溃退出,终端显示:
本文记录完整的排查过程和修复方案,适用于同类问题。
崩溃排查:从现象到根因
第一步:确认是配置文件问题还是资源问题
启动时退出代码 1 的常见原因有两种:
跳过配置文件启动测试:
--norc:跳过 ~/.bashrc
--noprofile:跳过 ~/.profile
如果能正常进入,说明是 Shell 配置文件的问题。继续逐个 source 排查:
用调试模式查看具体哪行出错:
终端会逐行打印执行的命令,最后几行输出前退出的那条就是根因。
第二步:注意默认 Shell 不是 bash 的情况
如果 ~/.bashrc 和 ~/.profile 都没有问题,但 WSL 仍然崩溃,可能是默认 Shell 被设为了不存在的程序。
检查当前默认 Shell:
如果显示 /bin/zsh 但 zsh 并未安装:
尝试直接以 zsh 启动:
如果报错 execvpe(/bin/zsh) failed: No such file or directory,确认是默认 Shell 指向了不存在的程序。
第三步:修复默认 Shell
从 Windows 端修复(WSL 无法进入时):
将 bowie 替换为你的 WSL 用户名。
从 WSL 内部修复(能进入时):
然后 wsl --shutdown 重启。
[!warning]
chsh 是 Linux 命令,必须在 WSL 内执行,不能在 PowerShell 中运行。如果 WSL 无法进入,使用上面的 Windows 端方案。
第四步:系统资源不足导致的崩溃
如果 Shell 配置和默认 Shell 都正常,但运行重负载后崩溃,检查是否是 OOM(Out of Memory):
如果看到类似 Out of memory: Killed process ... 的记录,就是内存不足。
典型场景: 同时运行 5 个 Next.js dev server,每个 server 占用 500MB-1.5GB,总计 3-7GB,加上 Node.js 编译、文件监听等开销,轻松超过 WSL2 默认的内存上限。
性能调优
根据物理内存分配资源
WSL2 默认内存策略是物理内存的 50%,但这不一定适合所有场景。以下是基于实际硬件的推荐配置:
16GB 物理内存
32GB 物理内存(推荐配置)
64GB 物理内存
配置说明:
启用自动内存回收
WSL2 的内存只增不减——分配后即使释放也不会还给 Windows,直到达到上限才触发回收。启用自动回收可以缓解这个问题:
可选值:
完整 .wslconfig 示例
文件路径:C:\Users\<用户名>\.wslconfig(不存在需手动创建,用 notepad C:\Users\Bowie\.wslconfig 即可)
[!tip]
修改 .wslconfig 后必须执行 wsl --shutdown 再重启才能生效。建议在 PowerShell 中执行 wsl --list --running 确认没有运行中的实例后再 shutdown。
Turborepo 多应用并发优化
问题现象
在 Turborepo 项目中同时启动 5 个 Next.js 应用,除了 WSL 内存压力外,还可能遇到:
- 内部 workspace 包解析失败(如
Can't resolve '@iflux-art/content-engine')
- 部分应用 ELIFECYCLE Command failed 后整个 dev 进程退出
- 热更新(HMR)延迟或丢失
workspace 包解析失败
确保内部包在 pnpm install 后正确 link:
如果包名不一致,修改 apps/docs/package.json 中的依赖声明使其与 packages/content-engine/package.json 的 name 字段完全匹配。然后重新安装:
单独调试某个应用
不需要每次都启动全部应用。Turborepo 支持按 filter 启动:
降低单个 dev server 的内存占用
在 next.config.ts 中调整:
验证资源分配效果
启动 dev server 后,在 WSL 内检查资源使用情况:
排查流程总结