# SteamSH 客户端打包指南

## 目录
- [环境要求](#环境要求)
- [打包方式](#打包方式)
  - [方式一：带开发者工具的打包（推荐调试用）](#方式一带开发者工具的打包推荐调试用)
  - [方式二：生产环境打包](#方式二生产环境打包)
  - [方式三：生成单个 exe 文件](#方式三生成单个-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 具有以下特性：
- **右键菜单**：在应用窗口内右键可以看到浏览器开发者工具选项
- **检查按钮**：可以在界面上直接打开开发者工具控制台查看日志
- 方便调试和查看前端控制台输出

```powershell
cd D:\code\steam\client-tauri

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

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

### 方式二：生产环境打包

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

```powershell
cd D:\code\steam\client-tauri

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

### 方式三：生成单个 exe 文件

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

```powershell
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

```powershell
# 复制 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 等

### 诊断工具使用

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

```batch
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. 使用打包脚本自动设置环境变量：
   ```powershell
   .\build-devtools.ps1   # 或
   .\build-prod.ps1
   ```

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

**检查方法**：
```powershell
# 使用 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 配置

```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 脚本内容

```powershell
$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*