buff3.0/client-tauri/BUILD-GUIDE.md

SteamSH 客户端打包指南

目录

• 环境要求
• 打包方式
  • 方式一：带开发者工具的打包（推荐调试用）
  • 方式二：生产环境打包
  • 方式三：生成单个 exe 文件
• 打包产物
• 部署指南
• 常见问题

---

环境要求

开发环境

• Windows 10/11 或 Windows Server
• Node.js 18+
• Rust 1.70+
• Visual Studio Build Tools 2019/2022
• OpenSSL-Win64 (FULL 版本，安装地址：C:\Program Files\OpenSSL-Win64)

运行时环境（目标服务器）

• Windows 10/11 或 Windows Server 2016+
• WebView2 运行时（程序会自动检测并提示安装）

---

打包方式

方式一：带开发者工具的打包（推荐调试用）

此方式打包的 exe 具有以下特性：

• 右键菜单：在应用窗口内右键可以看到浏览器开发者工具选项
• 检查按钮：可以在界面上直接打开开发者工具控制台查看日志
• 方便调试和查看前端控制台输出

cd D:\code\steam\client-tauri

# 执行带 devtools 的打包脚本
.\build-devtools.ps1

注意：此方式主要用于调试，生产部署建议使用方式二。

方式二：生产环境打包

生产环境打包生成纯净版 exe，无开发者工具：

cd D:\code\steam\client-tauri

# 生产环境打包
.\build-prod.ps1

方式三：生成单个 exe 文件

使用 standalone-build.ps1 生成单个可执行文件：

cd D:\code\steam\client-tauri

# 生成单个 exe
.\standalone-build.ps1

此脚本生成单个可执行文件 steamSH_standalone.exe，不包含 WebView2 bootstrapper。

---

打包产物

产物位置

产物	路径	大小	说明
带 devtools 的 exe	src-tauri/target/release/steamSH.exe	~21 MB	静态链接版，带开发者工具
生产版 exe	src-tauri/target/release/bundle/msi/steamSH_0.1.0_x64_en-US.msi	~11 MB	纯净版，无开发者工具
standalone exe	steamSH_standalone.exe	~21 MB	单文件版，无需 DLL
NSIS 安装包	src-tauri/target/release/bundle/nsis/steamSH_0.1.0_x64-setup.exe	-	需要手动修复 NSIS 配置

带 devtools 的 exe 特性

打包后双击运行 exe，按钮和功能：

1. 右键菜单：在应用窗口内任意位置点击右键，会出现开发者选项
2. 检查按钮：
   • Windows：按 F12 键打开开发者工具
   • 或者按 Ctrl+Shift+I 打开开发者工具
3. 控制台日志：
   • 在开发者工具的控制台(Console)标签页可以查看 Vue/Vite 的所有 console.log 输出
   • 可以查看网络请求、错误信息等

快速获取 exe

# 复制 devtools 版本到 dist-devtools 目录
Copy-Item "src-tauri\target\release\steamSH.exe" "dist-devtools\steamSH.exe"

# 复制 standalone 版本
Copy-Item "steamSH_standalone.exe" "dist-portable\steamSH.exe"

---

部署指南

部署文件清单

devtools 版本部署目录应包含以下文件：

dist-devtools/
├── steamSH.exe        # 主程序（带开发者工具）
├── vc_redist.x64.exe  # VC++ 运行库（可选）
├── README.md          # 使用说明

部署步骤

1. 将 dist-devtools 文件夹拷贝到目标电脑
2. 直接双击 steamSH.exe 运行

使用开发者工具

打包后的 exe 具有以下调试功能：

打开开发者工具的方法

1. 键盘快捷键：

   • F12：打开开发者工具
   • Ctrl+Shift+I：打开开发者工具
   • Ctrl+Shift+J：打开开发者工具并聚焦到控制台

2. 右键菜单：

   • 在应用窗口内任意位置点击右键
   • 选择"检查"或"Inspect"

3. 通过页面按钮（如果有）：

   • 如果前端代码添加了打开控制台的按钮

开发者工具功能

• Console（控制台）：查看 console.log() 输出的日志
• Elements：查看和调试 HTML/CSS
• Network：查看网络请求
• Sources：调试 JavaScript 代码
• Application：查看 localStorage、sessionStorage 等

诊断工具使用

如果应用启动失败，可以运行诊断工具：

diagnose.bat

诊断工具会检查：

1. WebView2 运行时是否安装
2. VC++ 运行库是否缺失
3. exe 文件是否存在
4. 日志文件内容

目标电脑依赖

依赖	必须	说明
Windows 10/11 或 Server 2016+	是	操作系统
WebView2 运行时	是	程序会自动提示安装
VC++ 2015-2022 Redistributable	否	大多数系统已安装

---

常见问题

Q1: 打包后 exe 提示找不到 libcrypto DLL

原因：OpenSSL 未正确静态链接。

解决方案：

1. 确保已安装 OpenSSL-Win64 FULL 版本

2. 确保静态库存在：

   C:\Program Files\OpenSSL-Win64\lib\VC\x64\MT\libcrypto_static.lib
   

3. 使用打包脚本自动设置环境变量：

   .\build-devtools.ps1   # 或
   .\build-prod.ps1
   

   Q2: 如何验证 exe 是否静态链接成功？

   检查方法：

   # 使用 dumpbin 检查依赖
   dumpbin /dependents "src-tauri\target\release\steamSH.exe"
   

静态链接成功的 exe 不应包含 libcrypto 或 libssl DLL 依赖。

Q3: devtools 版本和普通版本有什么区别？

特性	devtools 版本	普通版本
右键菜单	有	无
F12 打开控制台	支持	不支持
Console 日志	可查看	不可查看
文件大小	相同	相同
运行性能	相同	相同

Q4: NSIS 打包失败

错误：系统找不到指定的文件

解决方案：

1. 确保 src-tauri/icons/icon.ico 存在
2. 确保 src-tauri/license.txt 存在
3. 或使用 MSI 安装包代替 NSIS

Q5: 应用在目标电脑上闪退

1. 检查 WebView2 运行时是否安装
2. 运行 diagnose.bat 诊断
3. 检查 logs 目录下的日志文件
4. 常见原因：
   • WebView2 未安装
   • 服务器安全策略限制
   • 调试器检测（在生产环境会阻止运行，已禁用）

---

OpenSSL 静态链接说明

技术背景

Rust 的 openssl crate 默认动态链接系统 OpenSSL，生成的 exe 依赖外部 DLL 文件：

• libcrypto-3-x64.dll
• libssl-3-x64.dll

服务器系统通常没有预装这些 DLL，导致程序无法运行。

解决方案

打包脚本 build-devtools.ps1 和 build-prod.ps1 会自动：

1. 设置 OpenSSL 静态链接环境变量
2. 配置 Rust 静态链接 C 运行时
3. 编译时链接 OpenSSL 静态库

Cargo.toml 配置

[dependencies]
# OpenSSL 静态链接配置
# 设置环境变量后自动使用静态库
openssl = "0.10"

---

代码修改记录

2026-04-04 修改

1. 添加了 devtools 打包支持

   • 创建 build-devtools.ps1 脚本
   • 设置 TAURI_DEVTOOLS=1 环境变量启用开发者工具
   • 更新 tauri.conf.json 添加 devtools 配置

2. 创建了 OpenSSL 静态链接环境脚本

   • scripts/set-openssl-static-env.ps1 自动配置静态链接环境
   • 自动检测 OpenSSL 安装位置
   • 验证静态库是否存在

3. 更新了打包指南

   • 添加了带 devtools 打包的详细说明
   • 添加了如何使用开发者工具的说明
   • 添加了 devtools 版本和普通版本的对比

2026-04-01 修改

1. 禁用了虚拟机/服务器环境检测（security.rs）

   • 原代码会阻止在 VMware/VirtualBox 环境中运行
   • 已注释相关检测代码

2. 添加了启动错误对话框（main.rs）

   • 启动失败时显示友好提示而非直接闪退

3. 配置了 OpenSSL 静态链接

   • 使用 C:\Program Files\OpenSSL-Win64\lib\VC\x64\MT 目录下的静态库
   • 设置 OPENSSL_STATIC=1 环境变量

4. 更新了 tauri.conf.json

   • 窗口启动时居中显示
   • WebView2 bootstrapper 嵌入安装包

---

附录：build-devtools.ps1 脚本内容

$ErrorActionPreference = "Stop"
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8
Set-Location $PSScriptRoot

# 与 build-prod 一致：静态链接 OpenSSL
. (Join-Path $PSScriptRoot "scripts\set-openssl-static-env.ps1")

$env:DEFAULT_BACKEND_API_URL = "http://125.122.32.114:9000"

# 启用 devtools（右键菜单、检查按钮）
$env:TAURI_DEVTOOLS = "1"

Write-Host "========================================" -ForegroundColor Cyan
Write-Host "打包 SteamSH (带开发者工具)" -ForegroundColor Cyan
Write-Host "API 地址: $env:DEFAULT_BACKEND_API_URL" -ForegroundColor Cyan
Write-Host "DevTools: 已启用 (右键菜单 + 检查按钮)" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

npm run tauri build

Write-Host ""
Write-Host "打包完成！" -ForegroundColor Green
Write-Host "带 devtools 的 exe 位于: src-tauri\target\release\steamSH.exe"
Write-Host ""
Write-Host "提示：复制 exe 到其他电脑后，其他电脑需要安装 WebView2 运行时" -ForegroundColor Yellow

---

最后更新：2026-04-04