c#中必须安装microsoft.playwright而非playwright包，安装后需执行playwright install chromium等命令下载浏览器；截图黑屏多因headless渲染问题，可加参数或改用headful模式；登录态需复用ibrowsercontext实例并妥善管理生命周期。
Playwright 在 C# 中不能直接用 NuGet 安装 playwright 包（那是 Node.js 的），必须安装官方支持的 Microsoft.Playwright，否则项目根本跑不起来。
如何正确安装和初始化 Playwright
很多人卡在第一步：以为 dotnet add package playwright 能行，实际会报错找不到包。C# 生态里唯一受支持的是微软维护的 Microsoft.Playwright，且它不带浏览器二进制——需要额外执行驱动下载命令。
- 运行
dotnet add package Microsoft.Playwright添加引用 - 安装完后必须手动执行一次
playwright install chromium（或firefox/webkit），否则await Playwright.CreateAsync()会抛PlaywrightException: Failed to launch browser - 推荐在 CI/CD 或部署脚本中加入
playwright install --with-deps，避免因系统缺少依赖（如 libglib、libnss）导致启动失败 - 若用 Docker，基础镜像建议选
mcr.microsoft.com/dotnet/sdk:8.0-jammy（Ubuntu 22.04），别用 alpine——Playwright 不支持 musl
为什么 Page.ScreenshotAsync() 有时返回空文件或黑屏
不是代码写错了，而是 Chromium 启动时默认启用了 headless 模式，但某些页面依赖 GPU 或系统字体渲染，headless 下可能无法正确绘制。
- 临时解决：启动时加
--disable-gpu --no-sandbox --font-render-hinting=none参数（通过BrowserTypeLaunchOptions.Args传入） - 更稳妥的方式是改用
headful模式调试：new BrowserTypeLaunchOptions { Headless = false }，但生产环境禁用 - 截图前务必等关键元素加载完成，别只靠
WaitForTimeoutAsync(2000)，应使用await page.WaitForSelectorAsync("main")这类语义化等待 - 如果页面含 canvas 或 WebGL 内容，截图黑屏大概率是 Chromium 版本太旧，升级到 Playwright v1.40+（对应 Chromium 122+）可缓解
如何处理登录态保持与多页复用场景
每次 browser.NewContextAsync() 都是干净会话，page 关闭后 Cookie 和 localStorage 就丢了——这不是 bug，是设计如此。
- 要保持登录态，必须把
IBrowserContext提升为类字段或服务生命周期内单例，而不是在方法内临时创建 - 不要在
context.NewPageAsync()后反复调用page.GotoAsync()切换不同域名，跨域会清空部分存储；应为每个主域名单独建context - 需要导出/导入登录态时，用
context.StorageStateAsync()获取 JSON，再用new BrowserTypeLaunchOptions { StorageState = storageStatePath }加载 - 注意
context.CloseAsync()会销毁所有关联page，若只是想清理缓存，用context.ClearPermissionsAsync()+context.ClearCookiesAsync()更精准
Playwright 的 C# 绑定对异步取消支持较弱，比如 page.WaitForNavigationAsync() 传入 CancellationToken 可能不响应。真正稳定的做法是设超时参数（new PageWaitForNavigationOptions { Timeout = 15000 }），而不是依赖 token 中断。
