Playwright.NET 1.42.0 版本浏览器安装故障排查指南

问题现象

在 Windows 环境升级 Playwright.NET 至 1.42.0 版本后，执行浏览器安装命令（./playwright.ps1 install）时出现 MODULE_NOT_FOUND 错误。错误提示表明系统无法定位到关键模块文件，具体路径指向 .playwright\package\lib\cli\cli.js。

环境背景

• 操作系统：Windows 10
• 运行时：.NET 6.0
• 项目结构：包含共享库项目（直接引用 Playwright.NET NuGet 包）和测试项目（间接引用）

根本原因分析

该问题通常由版本冲突引起，当旧版本程序集（如 1.41）尝试与新版本驱动（1.42）交互时，会导致模块加载失败。在多项目解决方案中，这种冲突可能因以下情况加剧：

1. 项目间存在版本引用差异
2. 构建产物未完全清理
3. 文件系统权限限制

解决方案

标准修复流程

1. 彻底清理构建产物

   • 删除解决方案下所有项目的 bin 和 obj 目录
   • 执行 Clean Solution 操作
   • 建议使用命令行工具执行清理：dotnet clean

2. 权限检查

   • 以管理员身份运行 PowerShell
   • 验证目标目录（特别是 .playwright 文件夹）的写入权限

3. 版本一致性验证

   • 确保解决方案中所有项目引用相同版本的 Playwright.NET
   • 检查 NuGet 包引用是否出现版本冲突

复杂项目结构处理

对于包含共享库的多项目解决方案，建议：

1. 在共享库项目中集中管理 Playwright 依赖
2. 测试项目通过包引用（而非项目引用）使用共享库
3. 发布共享库时使用明确的版本号

预防措施

1. 升级最佳实践

   • 升级前备份项目
   • 按顺序执行：Clean → 升级 NuGet → Rebuild
   • 首次运行前手动删除 .playwright 缓存目录

2. 环境验证

   • 创建独立的测试项目验证基础功能
   • 使用 playwright --version 确认驱动版本

3. 持续集成配置

   • 在 CI 脚本中加入清理步骤
   • 设置明确的版本锁定机制

技术原理补充

Playwright.NET 采用分层架构设计：

• 上层：.NET 语言绑定
• 中层：Node.js 驱动层
• 底层：浏览器二进制

版本冲突通常发生在中层驱动与上层绑定的接口不匹配时。1.42.0 版本可能引入了驱动层的重要变更，导致旧版本绑定的预期接口无法满足。

总结

版本升级时的模块加载问题在自动化测试工具中较为常见。通过系统化的清理流程、权限管理和版本控制，可以有效预防此类问题。对于企业级项目，建议建立专门的兼容性测试流程，确保基础组件的平稳升级。