企业官网建设流程全解析

# PyInstaller 打包 exe 图标不显示？这篇文章帮你彻底解决！

## 🔍 问题背景

最近在用 PyInstaller 打包一个 PySide6 项目时，遇到了一个非常头疼的问题：**设置了图标但 exe 文件始终不显示**。经过一番折腾，终于找到了原因并解决了问题，现在分享给大家。

---

## 🎯 问题现象

在 `password_manager.spec` 文件中配置了图标：

```python
exe = EXE(
pyz,
a.scripts,
name='价值五亿项目',
console=False,
icon='src/resources/icon.ico', # 配置了图标
)
```

但打包后的 exe 文件始终显示默认图标，尝试了多种方法都无效。

---

## 🛠️ 排查过程

### 1. 检查图标文件格式

首先确认图标文件是否有效：

```python
from PIL import Image
img = Image.open('src/resources/icon.ico')
print('尺寸:', img.size) # 输出: (256, 202)
```

**发现问题！** 图标尺寸是 `256×202`，不是正方形！

### 2. 图标尺寸要求

Windows 的 `.ico` 图标文件有严格要求：

- ✅ **必须是正方形**（宽 = 高）

将图标转换为正方形并包含多种尺寸：

```python
from PIL import Image
img = Image.open('src/resources/icon.ico')

# 转换为正方形，居中裁剪
width, height = img.size
if width != height:
min_dim = min(width, height)
left = (width - min_dim) // 2
top = (height - min_dim) // 2
img = img.crop((left, top, left + min_dim, top + min_dim))

# 调整到 256×256
img = img.resize((256, 256), Image.LANCZOS)

# 保存为包含多种尺寸的 ICO 文件
img.save('src/resources/icon.ico', format='ICO',
sizes=[(16,16), (32,32), (48,48), (64,64), (128,128), (256,256)])
```

### 3. 中文名称编码问题

打包时发现终端显示乱码：

```
WARNING: The output directory "C:\D\pythonFiles\project\dist\windows\浠峰€间簲浜块」鐩?
```

**原因**：Windows 终端默认使用 GBK 编码，而 PyInstaller 使用 UTF-8 编码，中文名称会出现乱码，可能导致图标无法正确关联。

**解决方案**：将项目名称改为英文：

```python
name='PasswordManager', # 改为英文名称
```

### 4. UPX 压缩问题

UPX 压缩可能破坏图标资源，导致图标不显示。

**解决方案**：禁用 UPX 压缩或排除图标文件：

```python
exe = EXE(
pyz,
a.scripts,
upx=False, # 禁用 UPX 压缩
icon='src/resources/icon.ico',
)
```

### 5. Windows 图标缓存

即使打包成功，Windows 资源管理器可能缓存了旧图标。

**清除缓存方法**：

```bash
taskkill /f /im explorer.exe
del /f /s /q "%localappdata%\IconCache.db"
start explorer.exe
```

---

## ✅ 最终解决方案

综合以上排查，最终解决步骤：

1. **确保图标是正方形**（256×256）
2. **确保图标包含多种尺寸**
3. **使用英文项目名称**
4. **禁用 UPX 压缩**
5. **清除 Windows 图标缓存**

---

## 🔧 备用方案：手动修改图标

如果以上方法都无效，可以使用工具手动修改：

1. 下载 [Resource Hacker](http://www.angusj.com/resourcehacker/)
2. 打开 exe 文件
3. 展开左侧的 **Icon** 文件夹
4. 右键 → **Replace Icon** → 选择你的图标
5. 点击 **File** → **Save**

---

## 💡 总结

PyInstaller 打包图标不显示的常见原因：

| 问题 | 原因 | 解决方案 |
|------|------|----------|
| 图标不显示 | 图标不是正方形 | 转换为正方形 |
| 图标不显示 | 缺少多种尺寸 | 添加多种尺寸 |
| 图标不显示 | 中文名称乱码 | 改用英文名称 |
| 图标不显示 | UPX 压缩破坏 | 禁用 UPX |
| 图标不显示 | Windows 缓存 | 清除缓存 |