kefu/wechat_rpa/WINDOWS_EXE_BUILD.md

Windows EXE 打包说明

桌面端支持打包成单个 EXE 文件。首次打包需要联网安装构建依赖，后续可复用项目中的 .build-venv 和 .uv-cache。

一键打包

最简单的方法是直接双击项目目录中的：

一键打包EXE.bat

打包成功后会自动打开 dist 文件夹。若打包失败，命令窗口会保持打开并显示原因。

也可以在项目目录打开 PowerShell，运行：

powershell -ExecutionPolicy Bypass -File build_windows_exe.ps1

生成文件位于：

dist/ZhenAI-WeCom-Assistant-v1.0.0.exe

EXE 可以直接复制到其他 Windows 电脑运行，不需要另外安装 Python。程序运行数据保存在：

%LOCALAPPDATA%\ZhenYangTangRPA

其中包含云端配置缓存、客服名称本地偏好、聊天记录和登记数据。升级 EXE 不会清空这些资料。

目标电脑要求

• 支持 Windows 10 / Windows 11 64 位系统。
• 不需要安装 Python。
• 不需要安装 Microsoft WebView2 Runtime；EXE 已内置 Qt WebEngine 浏览器内核、浏览器子进程、中文语言包和资源文件。
• 需要能够访问云端配置域名和客服网页域名。
• 第一次打开单文件 EXE 会释放内置浏览器组件，因此启动时间可能比后续稍长。

默认界面使用内置 Qt WebEngine。只有开发调试时主动添加 --classic-ui 参数，才会改用依赖系统 Microsoft Edge 的经典界面，正常客户使用无需该参数。

每次执行一键打包时，脚本都会强制检查以下内容：

• 内置 QtWebEngineProcess.exe 浏览器子进程
• Qt WebEngine 核心资源和字符数据
• zh-CN 中文语言包
• VC++ 运行库
• 打包后 EXE 能否离线创建浏览器内核并成功加载测试页面

任意一项缺失或浏览器自检失败，打包脚本都会返回失败，BAT 窗口会保留错误信息，不会把该 EXE 当成成功版本交付。

发布新版本

1. 修改 app_version.py 中的 APP_VERSION，例如改为 1.0.1。
2. 重新运行 build_windows_exe.ps1。
3. 把生成的 EXE 上传到可下载地址。
4. 在云端管理后台“桌面端版本升级”中填写相同版本号和下载地址。
5. 确认下载地址可用后，再决定是否开启强制升级。

建议发布前在另一台 Windows 电脑上打开 EXE，确认软件能启动、能加载客服页面并能收到云端配置。

生成可安装版本

直接双击：

一键生成安装包.bat

它会先重新生成并验证桌面 EXE，再制作中文 Windows 安装包。第一次制作安装包时，会从 NuGet 软件包源下载固定版本的开源 NSIS 构建工具，并校验文件哈希，后续可直接复用。

安装包生成在：

dist\installer\甄AI客服-安装包-v1.0.0.exe

安装后的效果：

• 软件名称为“甄AI客服”
• 自动创建桌面快捷方式
• 自动创建开始菜单快捷方式
• 快捷方式名称和安装后的程序名称均为“甄AI客服”
• 安装到当前用户目录，无需管理员权限
• 可以在 Windows“已安装的应用”中正常卸载
• 覆盖安装新版时保留 %LOCALAPPDATA%\ZhenYangTangRPA 中的配置和聊天资料

说明：桌面和开始菜单中显示的是“甄AI客服”。安装目录里的主程序会保留打包时的英文文件名，这是 Qt WebEngine 浏览器内核正常启动所必需的，请不要手动重命名安装目录中的 EXE。