EG/build_scripts/ICON_GUIDE.md

EG 图标准备指南

构建安装程序需要准备应用程序图标，本指南说明如何创建和放置图标文件。

---

📋 所需图标

平台	文件名	格式	推荐尺寸	用途
Windows	icons/app.ico	ICO	256x256 (多尺寸)	可执行文件和安装程序图标
Linux	icons/app.png	PNG	256x256	AppImage 和桌面图标

---

🎨 图标要求

Windows ICO 文件

ICO 文件可以包含多个尺寸的图标：

• 必须包含: 256x256 (32位)
• 推荐包含: 48x48, 32x32, 16x16
• 可选: 128x128, 64x64

格式要求:

• 支持透明背景 (32位，带 Alpha 通道)
• 大图标使用 PNG 压缩
• 小图标使用 BMP 格式

Linux PNG 文件

• 尺寸: 256x256 像素
• 格式: PNG，带透明通道
• 色彩: RGBA (32位)

---

🔧 创建图标的方法

方法 1: 使用现有图片转换

如果你有 PNG/JPG 格式的 logo：

Windows (ICO):

# 使用 ImageMagick
convert logo.png -define icon:auto-resize=256,128,64,48,32,16 icons/app.ico

# 或在线工具
# https://convertio.co/png-ico/
# https://icoconvert.com/

Linux (PNG):

# 直接复制或调整大小
cp logo.png icons/app.png

# 或使用 ImageMagick 调整
convert logo.png -resize 256x256 icons/app.png

方法 2: 使用专业工具设计

工具	平台	类型	链接
Adobe Illustrator	Win/Mac	专业矢量	-
Figma	Web	免费在线	figma.com
Canva	Web	免费在线	canva.com
GIMP	Win/Mac/Linux	免费开源	gimp.org
Inkscape	Win/Mac/Linux	免费矢量	inkscape.org

方法 3: 使用 Python 脚本生成

如果你有源图片，可以使用 Python 生成：

#!/usr/bin/env python3
"""图标生成脚本"""

from PIL import Image
import os

# 源图片路径
source_image = "source_logo.png"  # 你的源图片
output_dir = "icons"

# 确保输出目录存在
os.makedirs(output_dir, exist_ok=True)

# 打开源图片
img = Image.open(source_image)

# 转换为 RGBA 模式 (确保透明通道)
if img.mode != 'RGBA':
    img = img.convert('RGBA')

# 生成 Windows ICO (多尺寸)
icon_sizes = [(16, 16), (32, 32), (48, 48), (64, 64), (128, 128), (256, 256)]
ico_images = []

for size in icon_sizes:
    resized = img.resize(size, Image.Resampling.LANCZOS)
    ico_images.append(resized)

# 保存 ICO (第一个图像作为根，其余作为子图标)
ico_images[0].save(
    os.path.join(output_dir, "app.ico"),
    format='ICO',
    sizes=[(i.width, i.height) for i in ico_images],
    append_images=ico_images[1:]
)

print(f"✓ 生成: {output_dir}/app.ico")

# 生成 Linux PNG (256x256)
png_size = (256, 256)
png_img = img.resize(png_size, Image.Resampling.LANCZOS)
png_img.save(os.path.join(output_dir, "app.png"), format='PNG')

print(f"✓ 生成: {output_dir}/app.png")

print("\n图标生成完成！")

使用方法:

# 安装依赖
pip install Pillow

# 运行脚本
python generate_icons.py

方法 4: 从项目中提取

如果项目中有现有图标资源：

# 查找项目中的图标文件
find . -name "*.ico" -o -name "*.png" | grep -i icon

# 复制到正确位置
cp 找到的图标文件 icons/app.ico
cp 找到的图标文件 icons/app.png

---

📁 目录结构

放置图标后，项目结构应为：

EG/
├── icons/
│   ├── app.ico          # Windows 图标 (必需)
│   ├── app.png          # Linux 图标 (必需)
│   └── ...              # 其他图标资源
├── build_scripts/
├── ...

---

✅ 验证图标

Windows

# 检查文件存在
Test-Path icons/app.ico

# 查看 ICO 内容 (需要工具)
# 使用 Resource Hacker: http://www.angusj.com/resourcehacker/

Linux

# 检查文件存在
ls -la icons/app.png

# 查看图片信息
file icons/app.png
identify icons/app.png  # 需要 ImageMagick

# 预览
xdg-open icons/app.png

---

🚀 测试图标

构建完成后，验证图标是否正确显示：

Windows

1. 可执行文件图标:

   # 检查 dist/EG_1.0.0/EG.exe 的图标
   # 在资源管理器中查看，应该显示你的图标
   

2. 安装程序图标:

   # 检查 dist/EG_Setup_v1.0.0_x64.exe 的图标
   

Linux

# 检查 AppImage 图标
./dist/EG-1.0.0-x86_64.AppImage --appimage-mount
ls squashfs-root/EG.png

---

🐛 常见问题

问题 1: ICO 文件无法识别

症状: Windows 显示默认图标

解决:

• 确保 ICO 包含 256x256 尺寸
• 使用专业工具重新生成
• 检查文件是否损坏

问题 2: Linux 图标不显示

症状: AppImage 使用默认图标

解决:

• 确认 icons/app.png 存在
• 检查文件权限: chmod 644 icons/app.png
• 确认 PNG 格式正确: file icons/app.png

问题 3: 图标模糊

症状: 图标显示模糊或锯齿

解决:

• 使用矢量源文件生成
• 确保包含多个尺寸
• 使用高质量缩放算法 (LANCZOS)

---

📦 快速开始

如果你没有现成的图标，可以先使用占位图标：

# Windows: 创建一个简单的 ICO
# 使用在线工具生成，或先跳过 (Nuitka 会使用默认图标)

# Linux: 创建一个简单的 PNG
python3 -c "
from PIL import Image
import os
os.makedirs('icons', exist_ok=True)
img = Image.new('RGBA', (256, 256), (100, 150, 255, 255))
img.save('icons/app.png')
print('Created placeholder icon')
"

注意: 发布前务必替换为正式图标！

---

🎨 设计建议

1. 简洁明了: 小尺寸下依然可识别
2. 品牌一致性: 与应用风格一致
3. 透明背景: 适应不同主题
4. 测试多尺寸: 确保 16x16 到 256x256 都清晰
5. 考虑暗色主题: 在深色背景下也可见

---

文档版本: 1.0