MyAvaloniaDemo/WSL部署说明.md

# Avalonia应用WSL Ubuntu部署说明

## 📋 概述
本文档说明如何将Avalonia应用发布到WSL Ubuntu环境中运行。

## 🚀 发布步骤

### 1. 生成Linux版本
在Windows PowerShell中运行以下命令之一：

**方法1: 使用批处理脚本**
```cmd
publish-linux.bat
```

**方法2: 使用PowerShell脚本**
```powershell
.\publish-linux.ps1
```

**方法3: 手动发布**
```cmd
dotnet publish -c Release -r linux-x64 --self-contained true -o "publish\linux-x64"
```

### 2. 拷贝到WSL Ubuntu

#### 方法1: 通过Windows文件系统访问
1. 在WSL Ubuntu中，Windows驱动器挂载在 `/mnt/` 下
2. 创建目标目录：
   ```bash
   mkdir -p ~/MyAvaloniaApp
   ```
3. 拷贝文件：
   ```bash
   cp -r /mnt/d/Log/MyAvaloniaApp/publish/linux-x64/* ~/MyAvaloniaApp/
   ```

#### 方法2: 通过WSL文件系统
1. 在Windows中，WSL文件系统位于：`\\wsl$\Ubuntu\home\<username>\`
2. 直接将 `publish\linux-x64\` 文件夹复制到WSL用户目录

### 3. 在Ubuntu中设置权限和运行

1. 进入应用目录：
   ```bash
   cd ~/MyAvaloniaApp
   ```

2. 设置执行权限：
   ```bash
   chmod +x MyAvaloniaApp
   ```

3. 运行应用：
   ```bash
   ./MyAvaloniaApp
   ```

## 🔧 系统要求

### Ubuntu系统要求
- Ubuntu 18.04 或更高版本
- 图形界面支持（X11或Wayland）
- X11相关系统库（**必须安装**）

### 自动安装依赖
**推荐方法**: 使用提供的安装脚本

在Windows中运行：
```cmd
install-wsl-deps.bat
```

或在WSL Ubuntu中手动运行：
```bash
# 拷贝脚本到WSL
cp /mnt/d/Log/MyAvaloniaApp/install-ubuntu-deps.sh ~/
chmod +x ~/install-ubuntu-deps.sh
./install-ubuntu-deps.sh
```

### 字体依赖安装
**重要**: 为了解决字体渲染问题，需要安装字体包：

```bash
# 安装常用字体包
sudo apt update
sudo apt install -y \
    fonts-dejavu-core \
    fonts-liberation \
    fonts-liberation2 \
    fontconfig \
    fonts-noto-core \
    fonts-noto-cjk
```

### 手动安装依赖
如果自动安装失败，可以手动安装：

```bash
sudo apt update
sudo apt install -y \
    libice6 libsm6 libx11-6 libx11-xcb1 libxcb1 \
    libxcb-icccm4 libxcb-image0 libxcb-keysyms1 \
    libxcb-randr0 libxcb-render-util0 libxcb-render0 \
    libxcb-shape0 libxcb-sync1 libxcb-util1 \
    libxcb-xfixes0 libxcb-xinerama0 libxcb-xkb1 \
    libxkbcommon-x11-0 libxkbcommon0 \
    libgl1-mesa-glx libgl1-mesa-dri libglib2.0-0 \
    libgthread-2.0-0 libgtk-3-0 libcairo-gobject2 \
    libgdk-pixbuf2.0-0 libpango-1.0-0 libpangocairo-1.0-0 \
    libatk1.0-0 libcairo2 libpixman-1-0 libxcomposite1 \
    libxcursor1 libxdamage1 libxext6 libxfixes3 \
    libxi6 libxrandr2 libxrender1 libxss1 libxtst6 \
    fonts-dejavu-core fonts-liberation fontconfig \
    libasound2 libatspi2.0-0 libdrm2 libxau6 libxdmcp6
```

### 图形界面支持
如果遇到图形界面问题，可能需要安装：
```bash
# 对于X11
sudo apt install x11-apps

# 对于Wayland
sudo apt install wayland-protocols
```

## 🐛 常见问题

### 1. libICE.so.6 缺失错误
**错误信息**: `System.DllNotFoundException: Unable to load shared library 'libICE.so.6'`

**解决方案**:
```bash
# 运行依赖安装脚本
./install-ubuntu-deps.sh

# 或手动安装X11库
sudo apt install libice6 libsm6 libx11-6
```

### 2. 权限问题
如果遇到权限错误：
```bash
chmod +x MyAvaloniaApp
```

### 3. 图形界面问题
如果应用无法显示窗口：
```bash
# 检查DISPLAY环境变量
echo $DISPLAY

# 设置DISPLAY（如果需要）
export DISPLAY=:0

# 如果使用WSLg，确保Windows版本支持
# 如果使用X11服务器，确保VcXsrv或Xming正在运行
```

### 4. 依赖库问题
如果缺少其他依赖库：
```bash
# 检查缺失的依赖
ldd MyAvaloniaApp

# 安装缺失的库
sudo apt install <missing-library-name>
```

### 5. 字体渲染问题
**问题**: 应用界面显示为占位符条状图标，文本无法正常显示

**解决方案**:
```bash
# 安装字体包
sudo apt install -y fonts-dejavu-core fonts-liberation fontconfig

# 刷新字体缓存
sudo fc-cache -fv

# 检查字体是否安装成功
fc-list | grep -i dejavu
```

**验证字体安装**:
```bash
# 查看可用字体
fc-list : family

# 测试字体渲染
echo "测试字体渲染" | xargs -I {} bash -c 'echo {} | figlet -f standard'
```

### 6. WSL图形界面设置
**方法1: 使用WSLg (Windows 11)**
- 确保Windows版本支持WSLg
- 无需额外配置

**方法2: 使用X11服务器**
- 安装VcXsrv或Xming
- 在WSL中设置: `export DISPLAY=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}'):0`

## 📁 文件结构
发布后的文件结构：
```
publish/linux-x64/
├── MyAvaloniaApp          # 主执行文件
├── MyAvaloniaApp.dll      # 应用程序集
├── MyAvaloniaApp.pdb      # 调试符号
├── Avalonia.*.dll         # Avalonia框架文件
├── System.*.dll           # .NET运行时文件
├── lib*.so                # 本地库文件
└── ...                    # 其他依赖文件
```

## 🔄 更新应用
当需要更新应用时：
1. 重新运行发布脚本
2. 停止旧版本应用
3. 替换文件
4. 重新运行

## 📝 注意事项
- 发布文件包含完整的.NET运行时，文件较大
- 确保WSL Ubuntu有足够的磁盘空间
- 首次运行可能需要较长时间来加载所有依赖
- 建议在发布前测试应用功能