Evidence项目在WSL/Linux环境下构建Parquet文件的故障排查与解决方案

问题背景

在使用Evidence项目进行数据处理时，开发者在WSL（Windows Subsystem for Linux）和Linux环境下遇到了一个特殊问题：当执行buildMultipartParquet操作时，系统会在写入最终Parquet文件时卡住。这个问题在macOS环境下完全正常，但在Ubuntu系统（包括WSL中的Ubuntu）上却会重现。

问题现象

具体表现为：

1. 程序能够成功生成临时的.0.parquet文件
2. 但在执行COPY命令将临时文件合并为最终Parquet文件时卡住
3. 使用VS Code的Parquet查看器验证临时文件内容正常
4. 最终的目标Parquet文件未能生成

技术分析

通过深入排查，发现问题根源在于DuckDB-WASM的网络连接行为：

1. WASM模块加载机制：当DuckDB-WASM首次执行Parquet文件写入操作时，会尝试从远程服务器获取必要的WASM扩展模块。

2. 代理设置问题：在配置了HTTPS代理（特别是包含用户名/密码认证的代理）的环境下，DuckDB-WASM无法正确处理代理认证，导致连接无限重试而非失败返回。

3. 环境差异：macOS环境下可能配置了无认证的代理或直接连接，因此能正常工作；而Linux/WSL环境下配置了需要认证的代理，触发了这个问题。

解决方案

临时解决方案

1. 移除或修改HTTPS_PROXY环境变量，避免使用包含用户名/密码的代理配置
2. 手动预缓存DuckDB扩展模块到~/.duckdb/extensions目录

长期建议

1. 在CI/CD环境中预先下载并缓存所有必要的DuckDB扩展
2. 考虑使用离线模式配置DuckDB-WASM
3. 等待DuckDB-WASM官方修复代理认证支持问题

技术启示

这个案例揭示了几个重要的技术要点：

1. 跨环境一致性：开发环境(macOS)和生产环境(Linux)的差异可能导致隐蔽的问题
2. 网络依赖：现代数据处理工具可能隐式依赖网络连接，这在受限网络环境中需要特别注意
3. 错误处理：良好的错误处理机制应该明确失败原因，而非无限重试
4. 代理兼容性：不是所有工具都能正确处理包含认证信息的代理配置

最佳实践建议

1. 在容器化部署时，预先打包所有必要的二进制依赖
2. 在CI/CD流水线中明确网络访问需求
3. 对于数据处理工具，考虑使用完全离线的部署模式
4. 定期验证不同环境下的构建一致性

这个问题虽然表面上是Evidence项目的一个构建问题，但实际上揭示了现代WebAssembly技术在数据处理应用中遇到的一个典型挑战，值得所有基于WASM技术栈的开发团队借鉴。