解决Mediago项目在Windows WSL环境下开发时的zx脚本执行问题

在Windows系统下使用WSL环境开发Mediago项目时，开发者可能会遇到一系列奇怪的错误。这些问题看似与Node.js版本或模块加载有关，但实际上源于一个更深层次的环境配置问题。

问题现象

当开发者在Windows系统上通过WSL运行pnpm dev命令时，可能会遇到以下几种错误：

1. 模块加载错误：Cannot find module 'fs/promises'
2. Node.js版本不兼容：This version of pnpm requires at least Node.js vXXX
3. 脚本执行错误：This: not found

这些错误看似毫无关联，但实际上它们都指向同一个根本原因。

问题根源分析

Mediago项目的开发脚本使用了zx库来执行命令行操作。zx库有一个特殊的行为：当检测到系统是Windows且存在WSL环境时，它会自动尝试通过WSL的Node.js环境来执行脚本，而不是使用宿主机的Node.js环境。

这就导致了以下问题链：

1. 开发者可能在Windows主机上安装了较新版本的Node.js（如v18.12.0）
2. 但WSL环境中可能保留了较旧版本的Node.js（如v12.22.6）
3. zx自动切换到WSL环境后，实际上是用旧版Node.js运行脚本
4. 旧版Node.js无法识别新版API（如fs/promises），也无法满足pnpm的版本要求

解决方案

要解决这个问题，我们需要显式地告诉zx在Windows环境下不要使用WSL，而是直接使用Windows的PowerShell。可以在项目的dev.ts脚本中添加以下配置：

if (process.platform === 'win32') {
    $.prefix = '';
    $.shell = 'pwsh.exe';
}

这段代码的作用是：

1. 检测当前平台是否为Windows（'win32'）
2. 如果是，则清除zx可能添加的任何前缀命令
3. 明确指定使用PowerShell（pwsh.exe）作为shell环境

深入理解

这个问题揭示了跨平台开发中的一个重要考虑点：环境隔离和显式控制。在混合使用Windows和WSL的开发环境中，工具链可能会做出一些自动化的选择，而这些选择不一定总是符合开发者的预期。

zx库的设计初衷是为了简化跨平台脚本编写，它尝试智能地处理不同环境下的shell差异。但在某些特定场景下，这种自动化行为反而会带来问题。因此，了解如何显式控制这些工具的行为是非常重要的开发技能。

最佳实践建议

1. 环境一致性：确保WSL和Windows主机上的Node.js版本保持一致
2. 显式控制：对于关键构建脚本，明确指定执行环境而不是依赖工具的自动判断
3. 环境检测：在脚本中添加环境检测逻辑，提前发现潜在的不兼容问题
4. 文档记录：在项目文档中注明这些特殊配置，帮助其他开发者快速上手

通过理解并应用这些解决方案，开发者可以避免在Windows WSL环境下开发Mediago项目时遇到的相关问题，提高开发效率。