feat(playwright): enable Playwright in production builds with custom browser path

Move Playwright from dev to production dependencies and implement robust browser
management for company deployment environment:

- Move playwright and playwright-core to dependencies
- Set PLAYWRIGHT_BROWSERS_PATH to user data directory before imports
- Add startup validation for Chromium browser with friendly error dialog
- Update build scripts to skip browser download during build process
- Configure electron-builder to unpack Playwright for native module access
- Add deployment documentation for browser setup in restricted environments

This allows manual browser installation in company environments where direct
downloads are blocked during build.

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
test
2026-03-07 19:03:29 +08:00
parent 9d15f7aca9
commit b3abad7fae
8 changed files with 444 additions and 14 deletions

176
BROWSER_DEPLOYMENT.md Normal file
View File

@@ -0,0 +1,176 @@
# Playwright 浏览器部署指南
## 概述
本文档为开发人员提供 ERPAuto 应用程序中 Playwright Chromium 浏览器的部署指南。文档说明如何将浏览器文件从开发机复制到目标用户机器,确保应用程序能够正常运行浏览器自动化任务。
**重要提示**:部署前请先阅读 [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) 了解版本信息。
## 目标路径
浏览器文件必须部署在以下路径:
```
%APPDATA%\erpauto\ms-playwright\chromium-1208\
```
完整展开路径示例Windows
```
C:\Users\<用户名>\AppData\Roaming\erpauto\ms-playwright\chromium-1208\
```
## 目录结构
部署完成后,目标目录结构应如下所示:
```
%APPDATA%\erpauto\ms-playwright\
└── chromium-1208/
└── chrome-win/
├── chrome.exe # 浏览器可执行文件
├── chrome_dll.dll
├── resources/
├── locales/
└── ... # 其他浏览器文件
```
**关键文件**`chrome-win/chrome.exe` 必须存在,否则浏览器无法启动。
## 部署步骤
### 步骤 1在开发机上准备
1. 确保开发机已安装正确版本的 Playwright
```bash
npm install playwright@1.58.2
```
2. 下载 Chromium 浏览器:
```bash
npx playwright install chromium
```
3. 定位开发机上的浏览器缓存目录:
```
C:\Users\<开发机用户名>\AppData\Local\ms-playwright\chromium-1208
```
### 步骤 2复制文件
1. **复制整个浏览器目录**
- 将开发机上的 `chromium-1208` 目录完整复制
- 不要只复制部分文件,确保所有子目录和文件都包含在内
2. **粘贴到目标路径**
- 在目标机器上创建目录:`%APPDATA%\erpauto\ms-playwright\`
-`chromium-1208` 目录粘贴到该路径下
3. **验证文件完整性**
- 确认目标路径存在:`%APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win\chrome.exe`
- 检查文件大小约为 280MB
### 步骤 3配置环境变量可选
如需确保应用程序使用正确的浏览器路径,可设置以下环境变量:
```batch
set PLAYWRIGHT_BROWSERS_PATH=%APPDATA%\erpauto\ms-playwright
```
或在应用程序代码中设置:
```javascript
process.env.PLAYWRIGHT_BROWSERS_PATH = path.join(app.getPath('userData'), 'ms-playwright')
```
## 验证步骤
部署完成后,执行以下验证步骤:
### 验证 1检查目录结构
在目标机器上运行:
```batch
dir %APPDATA%\erpauto\ms-playwright\chromium-1208\chrome-win\chrome.exe
```
应显示文件存在。
### 验证 2启动浏览器测试
运行 ERPAuto 应用程序,执行以下操作:
1. 登录应用程序
2. 进入「数据提取」页面
3. 输入一个有效订单号
4. 点击「开始提取」
5. 观察浏览器是否正常启动并执行任务
### 验证 3检查日志
查看应用程序日志,确认没有浏览器相关的错误信息:
- 无 "browser not found" 错误
- 无 "chromium revision not found" 错误
- 无 "PLAYWRIGHT_BROWSERS_PATH" 相关警告
## 故障排查
### 问题 1浏览器无法启动
**症状**:应用程序报错,提示找不到浏览器或启动失败。
**解决方案**
1. 确认修订号匹配(必须是 1208
2. 检查 `chrome-win/chrome.exe` 文件是否存在
3. 验证 `PLAYWRIGHT_BROWSERS_PATH` 环境变量设置正确
4. 确认目标机器具有相同的 Playwright 版本1.58.2
### 问题 2版本不匹配错误
**症状**:应用程序启动时报出版本冲突错误。
**解决方案**
1. 检查 `package.json` 中的 Playwright 版本是否为 1.58.2
2. 确认复制的 Chromium 修订号为 1208
3. 参考 [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) 核对所有版本信息
### 问题 3权限不足
**症状**:无法写入或读取浏览器目录。
**解决方案**
1. 确保目标目录具有适当的读写权限
2. 以管理员身份运行应用程序进行测试
3. 检查防病毒软件是否阻止了浏览器执行
### 问题 4路径错误
**症状**:应用程序在错误的位置查找浏览器文件。
**解决方案**
1. 确认 `%APPDATA%` 环境变量指向正确的用户目录
2. 检查应用程序是否正确解析了 `userData` 路径
3. 在代码中硬编码浏览器路径进行调试
## 注意事项
- **仅部署 Chromium**ERPAuto 只需要 Chromium 浏览器,不需要 Firefox 或 WebKit
- **版本一致性**:开发机和目标机器的 Playwright 版本必须一致
- **修订号匹配**Chromium 修订号1208必须完全匹配否则可能出现兼容性问题
- **文件完整性**:复制时确保所有文件完整,损坏的浏览器文件会导致启动失败
- **网络隔离环境**:目标机器如果无法访问互联网,必须提前部署浏览器文件,因为无法自动下载
## 参考文档
- [BROWSER_VERSIONS.md](./BROWSER_VERSIONS.md) - 版本信息和目录结构详情
- [README.md](./README.md) - 项目总体说明