generating-python-installer

Stars233,627

Forks35,611

UpdatedJune 16, 2026 at 01:17

Commercial-grade Python installer expert for Windows: Nuitka extreme compilation, dist slimming, DLL footprint analysis, and Inno Setup packaging to ship the smallest, fastest installers. Use only for advanced packaging/optimization (minimal size, fast startup), not basic script-to-exe conversion. 中文触发：Nuitka 极限优化、Python 商业打包、极限编译 Python、dist 瘦身、DLL 分析、最小安装包、最快启动、商业级打包风格

Installation

Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.

Source

affaan-m

affaan-m/ECC

View GitHub Repository View Creator Repositories

Download

Related occupationsSOC

Based on SOC occupation classification

Software DevelopersComputer and Mathematical Occupations·SOC 15-1252

SKILL.md

readonly

Generating Python Installer (Commercial-Grade)

You are a Python commercial deployment expert. Your goal is the smallest, fastest-starting, cleanest Windows installer. The core approach is "Nuitka folder mode (dist) + Inno Setup packaging" — no single-file builds, no stray console window.

When to Activate

Activate when the user explicitly asks for advanced Python packaging or size/startup optimization on Windows:

Nuitka extreme / commercial-grade compilation, smallest-size or fastest-startup builds
dist folder slimming, DLL footprint analysis, 32-bit vs 64-bit size tradeoffs
Inno Setup packaging with full metadata and a clean, residue-free uninstall

This skill targets advanced size/startup optimization — not basic one-file "script to exe" conversion.

How It Works

Confirm build parameters — app name, version, publisher, exe name, source/output dirs, icon. Never auto-fill; ask the user.
Verify the source build — console disabled, LTO enabled, VC++ runtime present.
Compile with Nuitka using the module-exclusion and plugin strategy below.
Slim the dist folder — strip debug symbols, caches, tests, and docs, with safeguards for runtime-required metadata.
Analyze DLLs to find and trim the largest dependencies.
Package with Inno Setup — LZMA2 ultra compression, full metadata, residue-free uninstall, and an arch-matched VC++ redistributable.

Examples

"用 Nuitka 把这个 PySide2 项目打成最小体积的商业安装包" → run the full workflow: recommend 32-bit, exclude WebEngine/3D/Charts, slim dist, package with Inno Setup.
"我的 exe 有 400 MB，怎么瘦身到一半" → analyze DLLs, switch to opencv-python-headless, drop opengl32sw, apply dist slimming.
"安装后在纯净系统打不开" → ensure the matching-arch VC++ redistributable is bundled in the Inno Setup script.

核心理念

坚持 "Nuitka 文件夹模式(dist) + Inno Setup 封装" 方案。拒绝单文件版，拒绝黑窗。

实战参考案例（生产级 PySide2 桌面应用，323 MB，含 OpenCV / Playwright）

项目概况

总体积: 323 MB
打包工具: PyInstaller 4.7 (32位)
主要依赖: PySide2 (22.52 MB), OpenCV (62.38 MB), Playwright (76.74 MB)
Python 版本: Python 3.8 (32位)
DLL 数量: 71 个，总计 93.23 MB

关键优化策略

PASS: 使用 32 位 Python → 体积减少 20-30%
PASS: base_library.zip 压缩标准库 → 0.74 MB
PASS: 精简模块排除 → 无 pytest/unittest/setuptools
PASS: 精简 Qt 插件 → 只保留必要插件

体积分布

组件	体积	占比	优化建议
playwright	76.74 MB	23.8%	非必要可移除
OpenCV	62.38 MB	19.3%	用 opencv-python-headless
PySide2	22.52 MB	7.0%	排除 WebEngine/3D/Charts
其他依赖	161.36 MB	49.9%	-

预期效果对比

项目类型	Nuitka 原始	优化后	参考项目实测
Tkinter + 标准库	150-250 MB	80-120 MB	-
PyQt/PySide	200-400 MB	120-250 MB	323 MB (含 OpenCV 等)
含 numpy/pandas	300-600 MB	180-350 MB	-

核心工作流 (Workflow) - WARNING: 严格执行

当用户请求打包时，按照以下步骤操作：

步骤 1：强制参数确认（FAIL: 禁止使用默认值）

WARNING: 重要规则：以下所有参数必须逐一向用户确认，禁止自动填充或使用默认值！

必须向用户询问并确认以下信息（等待用户明确回复后才能继续）：

参数	说明	示例
软件名称 (App Name)	软件显示名称	`红墨批注`
版本号 (Version)	语义化版本号	`1.0.0`
发布者/公司名 (Publisher)	控制面板显示的发布者	`YourCompany`
主程序 (Exe Name)	主可执行文件名	`RedInk.exe`
源路径 (Source Dir)	Nuitka dist 文件夹绝对路径	`D:\project\dist`
输出路径 (Output Dir)	安装包生成位置	`D:\project\output`
图标路径 (Icon Path)	.ico 文件绝对路径（可选但推荐）	`D:\project\icon.ico`
官网地址 (URL)	可选，用于控制面板链接	`https://example.com`

询问模板：

"请提供以下打包参数，我需要您逐一确认：

软件名称：

版本号：

发布者/公司名：

主程序文件名（如 xxx.exe）：

源路径（Nuitka dist 文件夹）：

输出路径（安装包保存位置）：

图标路径（.ico 文件，可留空）：

官网地址（可留空）：

请逐一填写，或回复"跳过"表示使用空值。"

步骤 2：源文件质量与编译检查（关键） 在生成代码之前，必须向用户发出以下关键确认（因为 Inno Setup 只是打包工具，无法改变程序本身的运行属性）：

"WARNING: 编译参数检查：

去黑窗：请确认您的 dist 文件夹是使用 nuitka --windows-console-mode=disable 编译的。（否则安装后依然会有黑框）

高性能：请确认是否使用了 --lto=yes。（否则启动速度可能不理想）

运行库：请确保 dist 文件夹内已包含必要的 VC++ 运行库，防止在纯净系统上无法运行。

确认源文件已准备好请回复"确认"，否则请先重新编译。"

步骤 3：生成代码 用户确认后，输出包含 完整元数据 和 卸载图标修复 的代码。

Nuitka 极限优化编译（基于参考项目经验）

一、32 位 vs 64 位选择策略

参考项目使用 32 位 Python 的原因：

组件	64位体积	32位体积	节省
python3x.dll	~4.5 MB	~3.8 MB	15%
Qt5Core.dll	~8 MB	~5 MB	37%
numpy	~30 MB	~20 MB	33%
总体	基准	-20~30%	-

推荐使用 32 位条件：

PASS: 程序内存占用 < 2GB
PASS: 不处理超大文件（< 2GB）
PASS: 目标用户是普通办公电脑

32 位编译方法：

# 1. 安装 32 位 Python（和 64 位可以共存）
# 下载地址：https://www.python.org/downloads/windows/

# 2. 用 32 位 Python 安装依赖
py -3.12-32 -m pip install -r requirements.txt

# 3. 用 32 位 Python 编译
py -3.12-32 -m nuitka --standalone ...你的参数

二、模块排除清单（参考项目验证过的）

安全排除列表（运行时不需要）：

unittest,test,pytest,_pytest,doctest,pdb,pdbpp,
setuptools,pip,distutils,pkg_resources,
email.mime,http.server,xmlrpc,pydoc

预期效果：节省 30-50 MB

三、GUI 框架专用优化

Tkinter 极限优化（推荐，最轻量）

nuitka --standalone --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=8 ^
    --enable-plugin=tk-inter ^
    --enable-plugin=anti-bloat ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb,pdbpp ^
    --nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
    --nofollow-import-to=email.mime,http.server,xmlrpc,pydoc ^
    --python-flag=no_docstrings ^
    --output-dir=dist ^
    --windows-icon-from-ico=icon.ico ^
    --remove-output ^
    main.py

预期体积：80-120 MB（优化后）

PyQt5 / PySide2 优化

nuitka --standalone --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=8 ^
    --enable-plugin=pyqt5 ^
    --enable-plugin=anti-bloat ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb ^
    --nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
    --nofollow-import-to=PyQt5.QtWebEngine,PyQt5.QtWebEngineWidgets ^
    --nofollow-import-to=PyQt5.Qt3D,PyQt5.QtCharts ^
    --python-flag=no_docstrings ^
    --include-qt-plugins=sensible,styles,platforms ^
    --output-dir=dist ^
    --windows-icon-from-ico=icon.ico ^
    --remove-output ^
    main.py

预期体积：120-250 MB（优化后）

四、一键编译脚本模板

保存为 build_optimized.bat（项目根目录）：

@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion

echo ========================================
echo Nuitka 极限优化编译（参考 参考项目）
echo ========================================

REM === 配置区域（请修改为你的实际值） ===
set APP_NAME=你的软件名
set MAIN_FILE=main.py
set ICON_FILE=icon.ico

REM === 自动检测 CPU 核心数 ===
REM 用 Windows 自带环境变量（wmic 在 Win11 22H2+ 已移除，探不到会让 --jobs=0 单线程编译）
set CPU_CORES=%NUMBER_OF_PROCESSORS%
if not defined CPU_CORES set CPU_CORES=4
set /a BUILD_JOBS=%CPU_CORES%

REM === 参考项目的模块排除清单 ===
set EXCLUDE_MODULES=unittest,test,pytest,_pytest,doctest,pdb,pdbpp
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,setuptools,pip,distutils,pkg_resources
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,email.mime,http.server,xmlrpc,pydoc

echo.
echo [1/4] 清理旧编译...
if exist dist rd /s /q dist
if exist build rd /s /q build

echo.
echo [2/4] Nuitka 编译中（应用 参考项目优化策略）...
echo - CPU 核心: %CPU_CORES% (使用 %BUILD_JOBS% 线程)
echo - 模块排除: %EXCLUDE_MODULES%
echo.

nuitka --standalone ^
    --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=%BUILD_JOBS% ^
    --enable-plugin=anti-bloat ^
    --enable-plugin=tk-inter ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=%EXCLUDE_MODULES% ^
    --python-flag=no_docstrings ^
    --output-dir=dist ^
    --windows-icon-from-ico=%ICON_FILE% ^
    --remove-output ^
    %MAIN_FILE%

if %errorlevel% neq 0 (
    echo.
    echo [错误] 编译失败！
    pause
    exit /b 1
)

echo.
echo [3/4] 统计编译结果...
for /f %%a in ('powershell -NoProfile -Command "(Get-ChildItem -LiteralPath 'dist\%APP_NAME%.dist' -Recurse -File | Measure-Object -Property Length -Sum).Sum"') do set TOTAL_SIZE=%%a
set TOTAL_SIZE=%TOTAL_SIZE:,=%
set /a SIZE_MB=%TOTAL_SIZE% / 1048576
echo - 编译后体积: %SIZE_MB% MB

echo.
echo [4/4] 执行瘦身清理（参考 参考项目策略）...
powershell -ExecutionPolicy Bypass -File slim_dist.ps1 -DistPath "dist\%APP_NAME%.dist"

echo.
echo ========================================
echo 编译完成！
echo ========================================
pause

五、dist 瘦身脚本（参考项目级别清理）

保存为 slim_dist.ps1（和 build_optimized.bat 同目录）：

param(
    [string]$DistPath
)

$ErrorActionPreference = "Continue"  # 不静默吞错：删除失败会显示出来，避免假成功

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "dist 瘦身清理（参考 参考项目策略）" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

if (-not (Test-Path $DistPath)) {
    Write-Host "[错误] 找不到目录: $DistPath" -ForegroundColor Red
    exit 1
}

# 统计初始体积
$InitialSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host "`n初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow

# 参考项目特征：没有 .pdb, .pyi, __pycache__, test 等
Write-Host "`n[应用 参考项目的清理策略...]" -ForegroundColor Green

# 1. 删除调试符号
Write-Host "`n[1/7] 删除 .pdb 调试符号..." -ForegroundColor Green
$pdbFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pdb -File
$pdbSize = ($pdbFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pdbFiles.Count -gt 0) {
    $pdbFiles | Remove-Item -Force
    Write-Host "  删除 $($pdbFiles.Count) 个文件，节省 $([math]::Round($pdbSize, 2)) MB"
} else {
    Write-Host "  未发现 .pdb 文件（已优化）" -ForegroundColor Gray
}

# 2. 删除类型提示
Write-Host "`n[2/7] 删除 .pyi 类型提示..." -ForegroundColor Green
$pyiFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyi -File
$pyiSize = ($pyiFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pyiFiles.Count -gt 0) {
    $pyiFiles | Remove-Item -Force
    Write-Host "  删除 $($pyiFiles.Count) 个文件，节省 $([math]::Round($pyiSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyi 文件（已优化）" -ForegroundColor Gray
}

# 3. 删除 __pycache__
Write-Host "`n[3/7] 删除 __pycache__ 缓存..." -ForegroundColor Green
$pycacheDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "__pycache__"
$pycacheSize = 0
foreach ($dir in $pycacheDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $pycacheSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($pycacheDirs.Count -gt 0) {
    Write-Host "  删除 $($pycacheDirs.Count) 个目录，节省 $([math]::Round($pycacheSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现 __pycache__（已优化）" -ForegroundColor Gray
}

# 4. 删除测试目录
Write-Host "`n[4/7] 删除 test/tests 测试目录..." -ForegroundColor Green
$testDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^tests?$' }
$testSize = 0
foreach ($dir in $testDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $testSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($testDirs.Count -gt 0) {
    Write-Host "  删除 $($testDirs.Count) 个目录，节省 $([math]::Round($testSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现测试目录（已优化）" -ForegroundColor Gray
}

# 5. 删除文档和示例
Write-Host "`n[5/7] 删除 docs/examples 文档目录..." -ForegroundColor Green
$docDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^(docs|examples|samples|demo)$' }
$docSize = 0
foreach ($dir in $docDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $docSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($docDirs.Count -gt 0) {
    Write-Host "  删除 $($docDirs.Count) 个目录，节省 $([math]::Round($docSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现文档目录（已优化）" -ForegroundColor Gray
}

# 6. 删除 .pyc 文件
Write-Host "`n[6/7] 删除 .pyc 字节码..." -ForegroundColor Green
$pycFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyc -File
$pycSize = ($pycFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pycFiles.Count -gt 0) {
    $pycFiles | Remove-Item -Force
    Write-Host "  删除 $($pycFiles.Count) 个文件，节省 $([math]::Round($pycSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyc 文件（已优化）" -ForegroundColor Gray
}

# 7. 精简 .dist-info 元数据
Write-Host "`n[7/7] 精简 .dist-info 元数据..." -ForegroundColor Green
$distInfoDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "*.dist-info"
$removedCount = 0
$removedSize = 0
foreach ($infoDir in $distInfoDirs) {
    # 仅删安装期记账文件；保留 METADATA 与 entry_points.txt（运行期被 importlib.metadata 读取，删除会破坏插件发现）
    $filesToRemove = @("RECORD", "INSTALLER", "direct_url.json")
    foreach ($fileName in $filesToRemove) {
        $file = Join-Path $infoDir.FullName $fileName
        if (Test-Path $file) {
            $size = (Get-Item $file).Length
            $removedSize += $size
            Remove-Item $file -Force
            $removedCount++
        }
    }
}
if ($removedCount -gt 0) {
    Write-Host "  删除 $removedCount 个元数据文件，节省 $([math]::Round($removedSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现可清理的元数据（已优化）" -ForegroundColor Gray
}

# 统计最终体积
$FinalSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
$SavedSize = $InitialSize - $FinalSize
$SavedPercent = if ($InitialSize -gt 0) { ($SavedSize / $InitialSize) * 100 } else { 0 }

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "清理完成！" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Cyan
Write-Host "初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow
Write-Host "最终体积: $([math]::Round($FinalSize, 2)) MB" -ForegroundColor Green
Write-Host "节省空间: $([math]::Round($SavedSize, 2)) MB ($([math]::Round($SavedPercent, 1))%)" -ForegroundColor Cyan
Write-Host "========================================`n" -ForegroundColor Cyan

# 对比 参考项目
Write-Host "[对比参考]" -ForegroundColor Yellow
Write-Host "参考项目总体积: 323 MB (包含 PyQt, OpenCV, Playwright 等重量级库)" -ForegroundColor Gray
Write-Host "如果你的项目是纯 Tkinter + 标准库，目标应该在 80-150 MB" -ForegroundColor Gray

预期效果：节省 15-30% 体积

六、DLL 依赖分析工具

保存为 analyze_dlls.py（用于找出体积大户）：

"""
DLL 依赖分析工具
参考 参考项目的 DLL 管理策略，帮助识别体积大户和优化建议
"""
import sys
from pathlib import Path

def analyze_dlls(dist_path: str):
    """分析 dist 目录中的 DLL 依赖"""
    dist_dir = Path(dist_path)

    if not dist_dir.exists():
        print(f"[错误] 目录不存在: {dist_path}")
        return

    print("=" * 70)
    print("DLL 依赖分析（参考 参考项目策略）")
    print("=" * 70)

    # 收集所有 DLL
    dll_files = list(dist_dir.rglob("*.dll"))

    if not dll_files:
        print("\n未发现 DLL 文件")
        return

    # 按大小排序
    dll_data = [(dll, dll.stat().st_size) for dll in dll_files]
    dll_data.sort(key=lambda x: x[1], reverse=True)

    total_size = sum(size for _, size in dll_data)

    print(f"\n总 DLL 数量: {len(dll_files)}")
    print(f"总 DLL 体积: {total_size / 1024 / 1024:.2f} MB\n")

    # 参考项目对比
    print("[对比参考] 参考项目的 DLL 情况:")
    print("  - 总数量: 71 个")
    print("  - 总体积: 93.23 MB")
    print("  - 最大的: libopenblas (26.85 MB), opengl32sw (15.25 MB)\n")

    # 分析大于 3MB 的 DLL
    large_dlls = [(dll, size) for dll, size in dll_data if size > 3 * 1024 * 1024]

    if large_dlls:
        print("=" * 70)
        print("WARNING:  大于 3MB 的 DLL（需重点关注）")
        print("=" * 70)

        for dll, size in large_dlls:
            size_mb = size / 1024 / 1024
            relative_path = dll.relative_to(dist_dir)
            name_lower = dll.name.lower()

            print(f"\n{size_mb:8.2f} MB  {dll.name}")
            print(f"           位置: {relative_path.parent}")

            # 优化建议
            suggestions = get_optimization_suggestion(name_lower)
            if suggestions:
                for suggestion in suggestions:
                    print(f"            {suggestion}")

    # 检查冗余 DLL
    print("\n" + "=" * 70)
    print(" 冗余检查")
    print("=" * 70)

    # 检查调试版本
    debug_dlls = [dll for dll, _ in dll_data if dll.stem.endswith('d')]
    if debug_dlls:
        print(f"\nWARNING:  发现 {len(debug_dlls)} 个调试版本 DLL（可以删除）:")
        for dll in debug_dlls:
            print(f"  - {dll.name}")
    else:
        print("\nPASS: 未发现调试版本 DLL（已优化）")

    # VC++ Runtime
    vc_runtimes = [dll for dll, _ in dll_data if 'vcruntime' in dll.name.lower() or 'msvcp' in dll.name.lower()]
    if vc_runtimes:
        print(f"\n[VC++ Runtime 库] 发现 {len(vc_runtimes)} 个:")
        for dll in vc_runtimes:
            size_mb = dll.stat().st_size / 1024 / 1024
            print(f"  - {dll.name} ({size_mb:.2f} MB)")
        print("   这些是必需的，参考项目也包含了这些文件")

    # 全部 DLL 列表
    print("\n" + "=" * 70)
    print(" 完整 DLL 列表（按体积排序，前 20）")
    print("=" * 70)
    print(f"\n{'体积 (MB)':>10}  {'文件名':<30}  位置")
    print("-" * 70)

    for dll, size in dll_data[:20]:
        size_mb = size / 1024 / 1024
        relative_path = dll.relative_to(dist_dir)
        location = str(relative_path.parent) if relative_path.parent != Path('.') else "根目录"
        print(f"{size_mb:10.2f}  {dll.name:<30}  {location}")

    if len(dll_data) > 20:
        remaining_size = sum(size for _, size in dll_data[20:]) / 1024 / 1024
        print(f"... 还有 {len(dll_data) - 20} 个 DLL，共 {remaining_size:.2f} MB")


def get_optimization_suggestion(dll_name: str) -> list:
    """根据 DLL 名称给出优化建议"""
    suggestions = []

    if "openblas" in dll_name or "mkl" in dll_name:
        suggestions.append("数学运算库，参考项目的 libopenblas 有 26.85 MB")
        suggestions.append("如不需要高性能计算可考虑轻量版")

    elif "opencv" in dll_name or "ffmpeg" in dll_name:
        suggestions.append("OpenCV 相关，参考项目的 opencv_videoio_ffmpeg 有 18.48 MB")
        suggestions.append("考虑用 opencv-python-headless")

    elif "qt5" in dll_name or "qt6" in dll_name or "pyside" in dll_name:
        suggestions.append("Qt 库，参考项目的 Qt5Core 有 5.13 MB")
        suggestions.append("可排除不需要的模块（WebEngine, 3D, Charts）")

    elif "opengl" in dll_name and "sw" in dll_name:
        suggestions.append("OpenGL 软件渲染器，参考项目保留了 15.25 MB")
        suggestions.append("通常可以删除（使用硬件渲染）")

    elif "d3dcompiler" in dll_name:
        suggestions.append("DirectX 编译器，参考项目有 3.53 MB")

    elif "mfc140" in dll_name:
        suggestions.append("MFC 库，参考项目有 4.89 MB")

    return suggestions


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python analyze_dlls.py <dist目录路径>")
        print("示例: python analyze_dlls.py dist/main.dist")
        sys.exit(1)

    analyze_dlls(sys.argv[1])

使用方法：

python analyze_dlls.py dist/你的软件名.dist

完整优化工作流

步骤 1：修改编译脚本配置

编辑 build_optimized.bat，修改这 3 行：

set APP_NAME=你的软件名      REM 改成实际名称
set MAIN_FILE=main.py        REM 你的主程序文件
set ICON_FILE=icon.ico       REM 你的图标文件

步骤 2：一键编译+瘦身

# 在项目根目录执行
build_optimized.bat

步骤 3：分析 DLL 依赖

python analyze_dlls.py dist/你的软件名.dist

步骤 4：根据分析结果优化

如果用了 OpenCV → 改用无头版

pip uninstall opencv-python
pip install opencv-python-headless

如果用了 Qt → 排除不需要的模块

# 在编译命令中添加
--nofollow-import-to=PyQt5.QtWebEngine,PyQt5.Qt3D,PyQt5.QtCharts

删除软件渲染器（如果不需要）

# 在 dist 目录执行
Remove-Item "opengl32sw.dll" -Force

VC++ 运行库处理方案

方案一：静态链接（推荐）

nuitka --static-libpython=yes ...

方案二：捆绑运行库安装（商业发布推荐）

在 Inno Setup 脚本中添加：

; WARNING: VC++ 运行库架构必须与 Python/Nuitka 构建架构一致。
; 本 skill 推荐 32 位 Python，故默认捆绑 vc_redist.x86.exe；
; 若用 64 位 Python 编译，请把下面两处改为 vc_redist.x64.exe。
[Files]
Source: "{#MySourceDir}\..\vc_redist.x86.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall

[Run]
Filename: "{tmp}\vc_redist.x86.exe"; Parameters: "/quiet /norestart"; StatusMsg: "正在安装运行库..."; Flags: waituntilterminated

下载地址：Microsoft Visual C++ Redistributable

Inno Setup 脚本模板（商业终极版）

; =====================================================================
;  WARNING: 商业级 Python 安装脚本 (Inno Setup 6.x)
;  特性：LZMA2 极限压缩 | 全中文 | 完整元数据 | 无残留卸载
;  参考：参考项目(323 MB, LZMA2 压缩)
; =====================================================================

; --- 1. 参数定义 ---
#define MyAppName        "{{APP_NAME}}"
#define MyAppVersion     "{{APP_VERSION}}"
#define MyAppPublisher   "{{PUBLISHER}}"
#define MyAppURL         "{{APP_URL}}"
#define MyAppExeName     "{{EXE_NAME}}"
#define MySourceDir      "{{SOURCE_DIR}}"
#define MyOutputDir      "{{OUTPUT_DIR}}"
;#define MyIconPath      "{{ICON_PATH}}"

[Setup]
; --- 身份识别 ---
AppId={{GENERATE_RANDOM_GUID}}
AppName={#MyAppName}
AppVersion={#MyAppVersion}
AppPublisher={#MyAppPublisher}
AppPublisherURL={#MyAppURL}
AppSupportURL={#MyAppURL}
AppUpdatesURL={#MyAppURL}

; --- 安装路径与权限 ---
DefaultDirName={autopf}\{#MyAppName}
DefaultGroupName={#MyAppName}
DisableDirPage=no
DisableProgramGroupPage=no
PrivilegesRequired=admin

; --- 输出设置 ---
OutputDir={#MyOutputDir}
OutputBaseFilename=Setup_{#MyAppName}_v{#MyAppVersion}

; --- 视觉体验 ---
WizardStyle=modern
#ifdef MyIconPath
SetupIconFile={#MyIconPath}
UninstallDisplayIcon={app}\{#MyAppExeName}
#endif

; ---  核心压缩 (参考 参考项目) ---
Compression=lzma2/ultra64
SolidCompression=yes
LZMAUseSeparateProcess=yes

; --- 架构 ---
; 注意：仅 64 位 Python 构建才设此项。本 skill 推荐 32 位 Python——
; 32 位构建请保持注释，使应用按 32 位安装并与上面捆绑的 vc_redist.x86.exe 匹配。
; 仅当用 64 位 Python 编译时才取消注释。
;ArchitecturesInstallIn64BitMode=x64compatible

[Languages]
Name: "chinesesimplified"; MessagesFile: "compiler:Languages\ChineseSimplified.isl"

[Files]
Source: "{#MySourceDir}\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs

[UninstallDelete]
Type: filesandordirs; Name: "{app}\*"

[Icons]
Name: "{autodesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; Tasks: desktopicon
Name: "{group}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"
Name: "{group}\卸载 {#MyAppName}"; Filename: "{uninstallexe}"

[Tasks]
Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked

[Run]
Filename: "{app}\{#MyAppExeName}"; Description: "{cm:LaunchProgram,{#MyAppName}}"; Flags: nowait postinstall skipifsilent

占位符说明

占位符	说明	示例值
`{{APP_NAME}}`	软件显示名称	`红墨批注`
`{{APP_VERSION}}`	版本号	`1.0.0`
`{{PUBLISHER}}`	发布者/公司名	`MyCompany`
`{{APP_URL}}`	官网地址	`https://example.com`
`{{EXE_NAME}}`	主程序文件名	`RedInk.exe`
`{{SOURCE_DIR}}`	Nuitka dist 文件夹路径	`D:\project\dist\RedInk.dist`
`{{OUTPUT_DIR}}`	安装包输出路径	`D:\project\output`
`{{ICON_PATH}}`	图标文件路径	`D:\project\icon.ico`
`{{GENERATE_RANDOM_GUID}}`	需生成唯一GUID	使用 Inno Setup "Tools > Generate GUID"

常见问题 (FAQ)

Q1: 安装后双击程序无反应？

打开 CMD，手动运行 exe 查看错误信息
检查是否缺少 VC++ 运行库
检查 Nuitka 编译是否成功

Q2: 安装包体积过大？

优化方法：

使用 32 位 Python 编译（节省 20-30%）
应用参考项目的模块排除清单
启用 Anti-Bloat 插件
执行 dist 文件夹瘦身脚本
分析 DLL，移除不必要的大文件

Q3: 杀毒软件误报？

解决方案：

提交到主流杀毒厂商进行白名单申请
购买代码签名证书（推荐：Sectigo, DigiCert）
避免使用 UPX 压缩

Q4: 安装时提示 Windows 已保护你的电脑？

购买 EV 代码签名证书（可立即获得信任）
普通代码签名证书需要积累安装量后逐渐获得信任

实战问题处理记录（更新 2026-02-07）

安装后提示缺少 python3xx.dll：必须使用 Nuitka --standalone；确认 dist 内存在该 dll；不要打单文件版。
安装后点击无反应：GUI 启动期可能被重依赖阻塞；将重依赖延迟到"开始导出"再 import；添加日志排查。
Nuitka + MinGW 在非 ASCII 路径报错：把源码复制到 ASCII 目录再编译；设置 PYTHONIOENCODING=utf-8。
Inno Setup 警告 x64 已弃用（仅 64 位构建需要 64 位安装模式时）：改为 ArchitecturesInstallIn64BitMode=x64compatible；32 位构建无需此项。
--disable-console 已废弃：改用 --windows-console-mode=disable。
dist 出现 _nuitka_temp.exe：在 [Files] 中排除它。

优化效果预期

优化组合	体积减少	启动提升	风险等级
基础编译	基准	基准	无
+ `--lto=yes`	5-10%	10-20%	PASS: 无
+ anti-bloat	15-25%	-	PASS: 无
+ 模块排除	20-35%	5%	PASS: 无
+ dist 瘦身	25-40%	-	PASS: 无
+ 32 位编译	40-60%	-	PASS: 无
全部组合	45-65%	15-25%	PASS: 无风险

WARNING: 不建议使用 UPX 压缩，虽然能进一步减小体积，但极易触发杀毒软件误报。

基于参考项目实战经验优化，助你打造商业级安装包！

name

generating-python-installer

description

Generating Python Installer (Commercial-Grade)

When to Activate

Activate when the user explicitly asks for advanced Python packaging or size/startup optimization on Windows:

Nuitka extreme / commercial-grade compilation, smallest-size or fastest-startup builds
dist folder slimming, DLL footprint analysis, 32-bit vs 64-bit size tradeoffs
Inno Setup packaging with full metadata and a clean, residue-free uninstall

This skill targets advanced size/startup optimization — not basic one-file "script to exe" conversion.

How It Works

Confirm build parameters — app name, version, publisher, exe name, source/output dirs, icon. Never auto-fill; ask the user.
Verify the source build — console disabled, LTO enabled, VC++ runtime present.
Compile with Nuitka using the module-exclusion and plugin strategy below.
Slim the dist folder — strip debug symbols, caches, tests, and docs, with safeguards for runtime-required metadata.
Analyze DLLs to find and trim the largest dependencies.
Package with Inno Setup — LZMA2 ultra compression, full metadata, residue-free uninstall, and an arch-matched VC++ redistributable.

Examples

"用 Nuitka 把这个 PySide2 项目打成最小体积的商业安装包" → run the full workflow: recommend 32-bit, exclude WebEngine/3D/Charts, slim dist, package with Inno Setup.
"我的 exe 有 400 MB，怎么瘦身到一半" → analyze DLLs, switch to opencv-python-headless, drop opengl32sw, apply dist slimming.
"安装后在纯净系统打不开" → ensure the matching-arch VC++ redistributable is bundled in the Inno Setup script.

核心理念

坚持 "Nuitka 文件夹模式(dist) + Inno Setup 封装" 方案。拒绝单文件版，拒绝黑窗。

实战参考案例（生产级 PySide2 桌面应用，323 MB，含 OpenCV / Playwright）

项目概况

总体积: 323 MB
打包工具: PyInstaller 4.7 (32位)
主要依赖: PySide2 (22.52 MB), OpenCV (62.38 MB), Playwright (76.74 MB)
Python 版本: Python 3.8 (32位)
DLL 数量: 71 个，总计 93.23 MB

关键优化策略

PASS: 使用 32 位 Python → 体积减少 20-30%
PASS: base_library.zip 压缩标准库 → 0.74 MB
PASS: 精简模块排除 → 无 pytest/unittest/setuptools
PASS: 精简 Qt 插件 → 只保留必要插件

体积分布

组件	体积	占比	优化建议
playwright	76.74 MB	23.8%	非必要可移除
OpenCV	62.38 MB	19.3%	用 opencv-python-headless
PySide2	22.52 MB	7.0%	排除 WebEngine/3D/Charts
其他依赖	161.36 MB	49.9%	-

预期效果对比

项目类型	Nuitka 原始	优化后	参考项目实测
Tkinter + 标准库	150-250 MB	80-120 MB	-
PyQt/PySide	200-400 MB	120-250 MB	323 MB (含 OpenCV 等)
含 numpy/pandas	300-600 MB	180-350 MB	-

核心工作流 (Workflow) - WARNING: 严格执行

当用户请求打包时，按照以下步骤操作：

步骤 1：强制参数确认（FAIL: 禁止使用默认值）

WARNING: 重要规则：以下所有参数必须逐一向用户确认，禁止自动填充或使用默认值！

必须向用户询问并确认以下信息（等待用户明确回复后才能继续）：

参数	说明	示例
软件名称 (App Name)	软件显示名称	`红墨批注`
版本号 (Version)	语义化版本号	`1.0.0`
发布者/公司名 (Publisher)	控制面板显示的发布者	`YourCompany`
主程序 (Exe Name)	主可执行文件名	`RedInk.exe`
源路径 (Source Dir)	Nuitka dist 文件夹绝对路径	`D:\project\dist`
输出路径 (Output Dir)	安装包生成位置	`D:\project\output`
图标路径 (Icon Path)	.ico 文件绝对路径（可选但推荐）	`D:\project\icon.ico`
官网地址 (URL)	可选，用于控制面板链接	`https://example.com`

询问模板：

"请提供以下打包参数，我需要您逐一确认：

软件名称：

版本号：

发布者/公司名：

主程序文件名（如 xxx.exe）：

源路径（Nuitka dist 文件夹）：

输出路径（安装包保存位置）：

图标路径（.ico 文件，可留空）：

官网地址（可留空）：

请逐一填写，或回复"跳过"表示使用空值。"

"WARNING: 编译参数检查：

去黑窗：请确认您的 dist 文件夹是使用 nuitka --windows-console-mode=disable 编译的。（否则安装后依然会有黑框）

高性能：请确认是否使用了 --lto=yes。（否则启动速度可能不理想）

运行库：请确保 dist 文件夹内已包含必要的 VC++ 运行库，防止在纯净系统上无法运行。

确认源文件已准备好请回复"确认"，否则请先重新编译。"

步骤 3：生成代码 用户确认后，输出包含 完整元数据 和 卸载图标修复 的代码。

Nuitka 极限优化编译（基于参考项目经验）

一、32 位 vs 64 位选择策略

参考项目使用 32 位 Python 的原因：

组件	64位体积	32位体积	节省
python3x.dll	~4.5 MB	~3.8 MB	15%
Qt5Core.dll	~8 MB	~5 MB	37%
numpy	~30 MB	~20 MB	33%
总体	基准	-20~30%	-

推荐使用 32 位条件：

PASS: 程序内存占用 < 2GB
PASS: 不处理超大文件（< 2GB）
PASS: 目标用户是普通办公电脑

32 位编译方法：

# 1. 安装 32 位 Python（和 64 位可以共存）
# 下载地址：https://www.python.org/downloads/windows/

# 2. 用 32 位 Python 安装依赖
py -3.12-32 -m pip install -r requirements.txt

# 3. 用 32 位 Python 编译
py -3.12-32 -m nuitka --standalone ...你的参数

二、模块排除清单（参考项目验证过的）

安全排除列表（运行时不需要）：

unittest,test,pytest,_pytest,doctest,pdb,pdbpp,
setuptools,pip,distutils,pkg_resources,
email.mime,http.server,xmlrpc,pydoc

预期效果：节省 30-50 MB

三、GUI 框架专用优化

Tkinter 极限优化（推荐，最轻量）

nuitka --standalone --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=8 ^
    --enable-plugin=tk-inter ^
    --enable-plugin=anti-bloat ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb,pdbpp ^
    --nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
    --nofollow-import-to=email.mime,http.server,xmlrpc,pydoc ^
    --python-flag=no_docstrings ^
    --output-dir=dist ^
    --windows-icon-from-ico=icon.ico ^
    --remove-output ^
    main.py

预期体积：80-120 MB（优化后）

PyQt5 / PySide2 优化

nuitka --standalone --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=8 ^
    --enable-plugin=pyqt5 ^
    --enable-plugin=anti-bloat ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=unittest,test,pytest,_pytest,doctest,pdb ^
    --nofollow-import-to=setuptools,pip,distutils,pkg_resources ^
    --nofollow-import-to=PyQt5.QtWebEngine,PyQt5.QtWebEngineWidgets ^
    --nofollow-import-to=PyQt5.Qt3D,PyQt5.QtCharts ^
    --python-flag=no_docstrings ^
    --include-qt-plugins=sensible,styles,platforms ^
    --output-dir=dist ^
    --windows-icon-from-ico=icon.ico ^
    --remove-output ^
    main.py

预期体积：120-250 MB（优化后）

四、一键编译脚本模板

保存为 build_optimized.bat（项目根目录）：

@echo off
chcp 65001 >nul
setlocal enabledelayedexpansion

echo ========================================
echo Nuitka 极限优化编译（参考 参考项目）
echo ========================================

REM === 配置区域（请修改为你的实际值） ===
set APP_NAME=你的软件名
set MAIN_FILE=main.py
set ICON_FILE=icon.ico

REM === 自动检测 CPU 核心数 ===
REM 用 Windows 自带环境变量（wmic 在 Win11 22H2+ 已移除，探不到会让 --jobs=0 单线程编译）
set CPU_CORES=%NUMBER_OF_PROCESSORS%
if not defined CPU_CORES set CPU_CORES=4
set /a BUILD_JOBS=%CPU_CORES%

REM === 参考项目的模块排除清单 ===
set EXCLUDE_MODULES=unittest,test,pytest,_pytest,doctest,pdb,pdbpp
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,setuptools,pip,distutils,pkg_resources
set EXCLUDE_MODULES=%EXCLUDE_MODULES%,email.mime,http.server,xmlrpc,pydoc

echo.
echo [1/4] 清理旧编译...
if exist dist rd /s /q dist
if exist build rd /s /q build

echo.
echo [2/4] Nuitka 编译中（应用 参考项目优化策略）...
echo - CPU 核心: %CPU_CORES% (使用 %BUILD_JOBS% 线程)
echo - 模块排除: %EXCLUDE_MODULES%
echo.

nuitka --standalone ^
    --windows-console-mode=disable ^
    --lto=yes ^
    --jobs=%BUILD_JOBS% ^
    --enable-plugin=anti-bloat ^
    --enable-plugin=tk-inter ^
    --noinclude-pytest-mode=nofollow ^
    --noinclude-setuptools-mode=nofollow ^
    --nofollow-import-to=%EXCLUDE_MODULES% ^
    --python-flag=no_docstrings ^
    --output-dir=dist ^
    --windows-icon-from-ico=%ICON_FILE% ^
    --remove-output ^
    %MAIN_FILE%

if %errorlevel% neq 0 (
    echo.
    echo [错误] 编译失败！
    pause
    exit /b 1
)

echo.
echo [3/4] 统计编译结果...
for /f %%a in ('powershell -NoProfile -Command "(Get-ChildItem -LiteralPath 'dist\%APP_NAME%.dist' -Recurse -File | Measure-Object -Property Length -Sum).Sum"') do set TOTAL_SIZE=%%a
set TOTAL_SIZE=%TOTAL_SIZE:,=%
set /a SIZE_MB=%TOTAL_SIZE% / 1048576
echo - 编译后体积: %SIZE_MB% MB

echo.
echo [4/4] 执行瘦身清理（参考 参考项目策略）...
powershell -ExecutionPolicy Bypass -File slim_dist.ps1 -DistPath "dist\%APP_NAME%.dist"

echo.
echo ========================================
echo 编译完成！
echo ========================================
pause

五、dist 瘦身脚本（参考项目级别清理）

保存为 slim_dist.ps1（和 build_optimized.bat 同目录）：

param(
    [string]$DistPath
)

$ErrorActionPreference = "Continue"  # 不静默吞错：删除失败会显示出来，避免假成功

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "dist 瘦身清理（参考 参考项目策略）" -ForegroundColor Cyan
Write-Host "========================================" -ForegroundColor Cyan

if (-not (Test-Path $DistPath)) {
    Write-Host "[错误] 找不到目录: $DistPath" -ForegroundColor Red
    exit 1
}

# 统计初始体积
$InitialSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
Write-Host "`n初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow

# 参考项目特征：没有 .pdb, .pyi, __pycache__, test 等
Write-Host "`n[应用 参考项目的清理策略...]" -ForegroundColor Green

# 1. 删除调试符号
Write-Host "`n[1/7] 删除 .pdb 调试符号..." -ForegroundColor Green
$pdbFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pdb -File
$pdbSize = ($pdbFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pdbFiles.Count -gt 0) {
    $pdbFiles | Remove-Item -Force
    Write-Host "  删除 $($pdbFiles.Count) 个文件，节省 $([math]::Round($pdbSize, 2)) MB"
} else {
    Write-Host "  未发现 .pdb 文件（已优化）" -ForegroundColor Gray
}

# 2. 删除类型提示
Write-Host "`n[2/7] 删除 .pyi 类型提示..." -ForegroundColor Green
$pyiFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyi -File
$pyiSize = ($pyiFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pyiFiles.Count -gt 0) {
    $pyiFiles | Remove-Item -Force
    Write-Host "  删除 $($pyiFiles.Count) 个文件，节省 $([math]::Round($pyiSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyi 文件（已优化）" -ForegroundColor Gray
}

# 3. 删除 __pycache__
Write-Host "`n[3/7] 删除 __pycache__ 缓存..." -ForegroundColor Green
$pycacheDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "__pycache__"
$pycacheSize = 0
foreach ($dir in $pycacheDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $pycacheSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($pycacheDirs.Count -gt 0) {
    Write-Host "  删除 $($pycacheDirs.Count) 个目录，节省 $([math]::Round($pycacheSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现 __pycache__（已优化）" -ForegroundColor Gray
}

# 4. 删除测试目录
Write-Host "`n[4/7] 删除 test/tests 测试目录..." -ForegroundColor Green
$testDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^tests?$' }
$testSize = 0
foreach ($dir in $testDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $testSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($testDirs.Count -gt 0) {
    Write-Host "  删除 $($testDirs.Count) 个目录，节省 $([math]::Round($testSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现测试目录（已优化）" -ForegroundColor Gray
}

# 5. 删除文档和示例
Write-Host "`n[5/7] 删除 docs/examples 文档目录..." -ForegroundColor Green
$docDirs = Get-ChildItem -Path $DistPath -Recurse -Directory | Where-Object { $_.Name -match '^(docs|examples|samples|demo)$' }
$docSize = 0
foreach ($dir in $docDirs) {
    $size = (Get-ChildItem -Path $dir.FullName -Recurse -File | Measure-Object -Property Length -Sum).Sum
    $docSize += $size
    Remove-Item -Path $dir.FullName -Recurse -Force
}
if ($docDirs.Count -gt 0) {
    Write-Host "  删除 $($docDirs.Count) 个目录，节省 $([math]::Round($docSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现文档目录（已优化）" -ForegroundColor Gray
}

# 6. 删除 .pyc 文件
Write-Host "`n[6/7] 删除 .pyc 字节码..." -ForegroundColor Green
$pycFiles = Get-ChildItem -Path $DistPath -Recurse -Include *.pyc -File
$pycSize = ($pycFiles | Measure-Object -Property Length -Sum).Sum / 1MB
if ($pycFiles.Count -gt 0) {
    $pycFiles | Remove-Item -Force
    Write-Host "  删除 $($pycFiles.Count) 个文件，节省 $([math]::Round($pycSize, 2)) MB"
} else {
    Write-Host "  未发现 .pyc 文件（已优化）" -ForegroundColor Gray
}

# 7. 精简 .dist-info 元数据
Write-Host "`n[7/7] 精简 .dist-info 元数据..." -ForegroundColor Green
$distInfoDirs = Get-ChildItem -Path $DistPath -Recurse -Directory -Filter "*.dist-info"
$removedCount = 0
$removedSize = 0
foreach ($infoDir in $distInfoDirs) {
    # 仅删安装期记账文件；保留 METADATA 与 entry_points.txt（运行期被 importlib.metadata 读取，删除会破坏插件发现）
    $filesToRemove = @("RECORD", "INSTALLER", "direct_url.json")
    foreach ($fileName in $filesToRemove) {
        $file = Join-Path $infoDir.FullName $fileName
        if (Test-Path $file) {
            $size = (Get-Item $file).Length
            $removedSize += $size
            Remove-Item $file -Force
            $removedCount++
        }
    }
}
if ($removedCount -gt 0) {
    Write-Host "  删除 $removedCount 个元数据文件，节省 $([math]::Round($removedSize / 1MB, 2)) MB"
} else {
    Write-Host "  未发现可清理的元数据（已优化）" -ForegroundColor Gray
}

# 统计最终体积
$FinalSize = (Get-ChildItem -Path $DistPath -Recurse -File | Measure-Object -Property Length -Sum).Sum / 1MB
$SavedSize = $InitialSize - $FinalSize
$SavedPercent = if ($InitialSize -gt 0) { ($SavedSize / $InitialSize) * 100 } else { 0 }

Write-Host "`n========================================" -ForegroundColor Cyan
Write-Host "清理完成！" -ForegroundColor Green
Write-Host "========================================" -ForegroundColor Cyan
Write-Host "初始体积: $([math]::Round($InitialSize, 2)) MB" -ForegroundColor Yellow
Write-Host "最终体积: $([math]::Round($FinalSize, 2)) MB" -ForegroundColor Green
Write-Host "节省空间: $([math]::Round($SavedSize, 2)) MB ($([math]::Round($SavedPercent, 1))%)" -ForegroundColor Cyan
Write-Host "========================================`n" -ForegroundColor Cyan

# 对比 参考项目
Write-Host "[对比参考]" -ForegroundColor Yellow
Write-Host "参考项目总体积: 323 MB (包含 PyQt, OpenCV, Playwright 等重量级库)" -ForegroundColor Gray
Write-Host "如果你的项目是纯 Tkinter + 标准库，目标应该在 80-150 MB" -ForegroundColor Gray

预期效果：节省 15-30% 体积

六、DLL 依赖分析工具

保存为 analyze_dlls.py（用于找出体积大户）：

"""
DLL 依赖分析工具
参考 参考项目的 DLL 管理策略，帮助识别体积大户和优化建议
"""
import sys
from pathlib import Path

def analyze_dlls(dist_path: str):
    """分析 dist 目录中的 DLL 依赖"""
    dist_dir = Path(dist_path)

    if not dist_dir.exists():
        print(f"[错误] 目录不存在: {dist_path}")
        return

    print("=" * 70)
    print("DLL 依赖分析（参考 参考项目策略）")
    print("=" * 70)

    # 收集所有 DLL
    dll_files = list(dist_dir.rglob("*.dll"))

    if not dll_files:
        print("\n未发现 DLL 文件")
        return

    # 按大小排序
    dll_data = [(dll, dll.stat().st_size) for dll in dll_files]
    dll_data.sort(key=lambda x: x[1], reverse=True)

    total_size = sum(size for _, size in dll_data)

    print(f"\n总 DLL 数量: {len(dll_files)}")
    print(f"总 DLL 体积: {total_size / 1024 / 1024:.2f} MB\n")

    # 参考项目对比
    print("[对比参考] 参考项目的 DLL 情况:")
    print("  - 总数量: 71 个")
    print("  - 总体积: 93.23 MB")
    print("  - 最大的: libopenblas (26.85 MB), opengl32sw (15.25 MB)\n")

    # 分析大于 3MB 的 DLL
    large_dlls = [(dll, size) for dll, size in dll_data if size > 3 * 1024 * 1024]

    if large_dlls:
        print("=" * 70)
        print("WARNING:  大于 3MB 的 DLL（需重点关注）")
        print("=" * 70)

        for dll, size in large_dlls:
            size_mb = size / 1024 / 1024
            relative_path = dll.relative_to(dist_dir)
            name_lower = dll.name.lower()

            print(f"\n{size_mb:8.2f} MB  {dll.name}")
            print(f"           位置: {relative_path.parent}")

            # 优化建议
            suggestions = get_optimization_suggestion(name_lower)
            if suggestions:
                for suggestion in suggestions:
                    print(f"            {suggestion}")

    # 检查冗余 DLL
    print("\n" + "=" * 70)
    print(" 冗余检查")
    print("=" * 70)

    # 检查调试版本
    debug_dlls = [dll for dll, _ in dll_data if dll.stem.endswith('d')]
    if debug_dlls:
        print(f"\nWARNING:  发现 {len(debug_dlls)} 个调试版本 DLL（可以删除）:")
        for dll in debug_dlls:
            print(f"  - {dll.name}")
    else:
        print("\nPASS: 未发现调试版本 DLL（已优化）")

    # VC++ Runtime
    vc_runtimes = [dll for dll, _ in dll_data if 'vcruntime' in dll.name.lower() or 'msvcp' in dll.name.lower()]
    if vc_runtimes:
        print(f"\n[VC++ Runtime 库] 发现 {len(vc_runtimes)} 个:")
        for dll in vc_runtimes:
            size_mb = dll.stat().st_size / 1024 / 1024
            print(f"  - {dll.name} ({size_mb:.2f} MB)")
        print("   这些是必需的，参考项目也包含了这些文件")

    # 全部 DLL 列表
    print("\n" + "=" * 70)
    print(" 完整 DLL 列表（按体积排序，前 20）")
    print("=" * 70)
    print(f"\n{'体积 (MB)':>10}  {'文件名':<30}  位置")
    print("-" * 70)

    for dll, size in dll_data[:20]:
        size_mb = size / 1024 / 1024
        relative_path = dll.relative_to(dist_dir)
        location = str(relative_path.parent) if relative_path.parent != Path('.') else "根目录"
        print(f"{size_mb:10.2f}  {dll.name:<30}  {location}")

    if len(dll_data) > 20:
        remaining_size = sum(size for _, size in dll_data[20:]) / 1024 / 1024
        print(f"... 还有 {len(dll_data) - 20} 个 DLL，共 {remaining_size:.2f} MB")


def get_optimization_suggestion(dll_name: str) -> list:
    """根据 DLL 名称给出优化建议"""
    suggestions = []

    if "openblas" in dll_name or "mkl" in dll_name:
        suggestions.append("数学运算库，参考项目的 libopenblas 有 26.85 MB")
        suggestions.append("如不需要高性能计算可考虑轻量版")

    elif "opencv" in dll_name or "ffmpeg" in dll_name:
        suggestions.append("OpenCV 相关，参考项目的 opencv_videoio_ffmpeg 有 18.48 MB")
        suggestions.append("考虑用 opencv-python-headless")

    elif "qt5" in dll_name or "qt6" in dll_name or "pyside" in dll_name:
        suggestions.append("Qt 库，参考项目的 Qt5Core 有 5.13 MB")
        suggestions.append("可排除不需要的模块（WebEngine, 3D, Charts）")

    elif "opengl" in dll_name and "sw" in dll_name:
        suggestions.append("OpenGL 软件渲染器，参考项目保留了 15.25 MB")
        suggestions.append("通常可以删除（使用硬件渲染）")

    elif "d3dcompiler" in dll_name:
        suggestions.append("DirectX 编译器，参考项目有 3.53 MB")

    elif "mfc140" in dll_name:
        suggestions.append("MFC 库，参考项目有 4.89 MB")

    return suggestions


if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("用法: python analyze_dlls.py <dist目录路径>")
        print("示例: python analyze_dlls.py dist/main.dist")
        sys.exit(1)

    analyze_dlls(sys.argv[1])

使用方法：

python analyze_dlls.py dist/你的软件名.dist

完整优化工作流

步骤 1：修改编译脚本配置

编辑 build_optimized.bat，修改这 3 行：

set APP_NAME=你的软件名      REM 改成实际名称
set MAIN_FILE=main.py        REM 你的主程序文件
set ICON_FILE=icon.ico       REM 你的图标文件

步骤 2：一键编译+瘦身

# 在项目根目录执行
build_optimized.bat

步骤 3：分析 DLL 依赖

python analyze_dlls.py dist/你的软件名.dist

步骤 4：根据分析结果优化

如果用了 OpenCV → 改用无头版

pip uninstall opencv-python
pip install opencv-python-headless

如果用了 Qt → 排除不需要的模块

# 在编译命令中添加
--nofollow-import-to=PyQt5.QtWebEngine,PyQt5.Qt3D,PyQt5.QtCharts

删除软件渲染器（如果不需要）

# 在 dist 目录执行
Remove-Item "opengl32sw.dll" -Force

VC++ 运行库处理方案

方案一：静态链接（推荐）

nuitka --static-libpython=yes ...

方案二：捆绑运行库安装（商业发布推荐）

在 Inno Setup 脚本中添加：

; WARNING: VC++ 运行库架构必须与 Python/Nuitka 构建架构一致。
; 本 skill 推荐 32 位 Python，故默认捆绑 vc_redist.x86.exe；
; 若用 64 位 Python 编译，请把下面两处改为 vc_redist.x64.exe。
[Files]
Source: "{#MySourceDir}\..\vc_redist.x86.exe"; DestDir: "{tmp}"; Flags: deleteafterinstall

[Run]
Filename: "{tmp}\vc_redist.x86.exe"; Parameters: "/quiet /norestart"; StatusMsg: "正在安装运行库..."; Flags: waituntilterminated

下载地址：Microsoft Visual C++ Redistributable

Inno Setup 脚本模板（商业终极版）

; =====================================================================
;  WARNING: 商业级 Python 安装脚本 (Inno Setup 6.x)
;  特性：LZMA2 极限压缩 | 全中文 | 完整元数据 | 无残留卸载
;  参考：参考项目(323 MB, LZMA2 压缩)
; =====================================================================

; --- 1. 参数定义 ---
#define MyAppName        "{{APP_NAME}}"
#define MyAppVersion     "{{APP_VERSION}}"
#define MyAppPublisher   "{{PUBLISHER}}"
#define MyAppURL         "{{APP_URL}}"
#define MyAppExeName     "{{EXE_NAME}}"
#define MySourceDir      "{{SOURCE_DIR}}"
#define MyOutputDir      "{{OUTPUT_DIR}}"
;#define MyIconPath      "{{ICON_PATH}}"

[Setup]
; --- 身份识别 ---
AppId={{GENERATE_RANDOM_GUID}}
AppName={#MyAppName}
AppVersion={#MyAppVersion}
AppPublisher={#MyAppPublisher}
AppPublisherURL={#MyAppURL}
AppSupportURL={#MyAppURL}
AppUpdatesURL={#MyAppURL}

; --- 安装路径与权限 ---
DefaultDirName={autopf}\{#MyAppName}
DefaultGroupName={#MyAppName}
DisableDirPage=no
DisableProgramGroupPage=no
PrivilegesRequired=admin

; --- 输出设置 ---
OutputDir={#MyOutputDir}
OutputBaseFilename=Setup_{#MyAppName}_v{#MyAppVersion}

; --- 视觉体验 ---
WizardStyle=modern
#ifdef MyIconPath
SetupIconFile={#MyIconPath}
UninstallDisplayIcon={app}\{#MyAppExeName}
#endif

; ---  核心压缩 (参考 参考项目) ---
Compression=lzma2/ultra64
SolidCompression=yes
LZMAUseSeparateProcess=yes

; --- 架构 ---
; 注意：仅 64 位 Python 构建才设此项。本 skill 推荐 32 位 Python——
; 32 位构建请保持注释，使应用按 32 位安装并与上面捆绑的 vc_redist.x86.exe 匹配。
; 仅当用 64 位 Python 编译时才取消注释。
;ArchitecturesInstallIn64BitMode=x64compatible

[Languages]
Name: "chinesesimplified"; MessagesFile: "compiler:Languages\ChineseSimplified.isl"

[Files]
Source: "{#MySourceDir}\*"; DestDir: "{app}"; Flags: ignoreversion recursesubdirs createallsubdirs

[UninstallDelete]
Type: filesandordirs; Name: "{app}\*"

[Icons]
Name: "{autodesktop}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"; Tasks: desktopicon
Name: "{group}\{#MyAppName}"; Filename: "{app}\{#MyAppExeName}"
Name: "{group}\卸载 {#MyAppName}"; Filename: "{uninstallexe}"

[Tasks]
Name: "desktopicon"; Description: "{cm:CreateDesktopIcon}"; GroupDescription: "{cm:AdditionalIcons}"; Flags: unchecked

[Run]
Filename: "{app}\{#MyAppExeName}"; Description: "{cm:LaunchProgram,{#MyAppName}}"; Flags: nowait postinstall skipifsilent

占位符说明

占位符	说明	示例值
`{{APP_NAME}}`	软件显示名称	`红墨批注`
`{{APP_VERSION}}`	版本号	`1.0.0`
`{{PUBLISHER}}`	发布者/公司名	`MyCompany`
`{{APP_URL}}`	官网地址	`https://example.com`
`{{EXE_NAME}}`	主程序文件名	`RedInk.exe`
`{{SOURCE_DIR}}`	Nuitka dist 文件夹路径	`D:\project\dist\RedInk.dist`
`{{OUTPUT_DIR}}`	安装包输出路径	`D:\project\output`
`{{ICON_PATH}}`	图标文件路径	`D:\project\icon.ico`
`{{GENERATE_RANDOM_GUID}}`	需生成唯一GUID	使用 Inno Setup "Tools > Generate GUID"

常见问题 (FAQ)

Q1: 安装后双击程序无反应？

打开 CMD，手动运行 exe 查看错误信息
检查是否缺少 VC++ 运行库
检查 Nuitka 编译是否成功

Q2: 安装包体积过大？

优化方法：

使用 32 位 Python 编译（节省 20-30%）
应用参考项目的模块排除清单
启用 Anti-Bloat 插件
执行 dist 文件夹瘦身脚本
分析 DLL，移除不必要的大文件

Q3: 杀毒软件误报？

解决方案：

提交到主流杀毒厂商进行白名单申请
购买代码签名证书（推荐：Sectigo, DigiCert）
避免使用 UPX 压缩

Q4: 安装时提示 Windows 已保护你的电脑？

购买 EV 代码签名证书（可立即获得信任）
普通代码签名证书需要积累安装量后逐渐获得信任

实战问题处理记录（更新 2026-02-07）

安装后提示缺少 python3xx.dll：必须使用 Nuitka --standalone；确认 dist 内存在该 dll；不要打单文件版。
安装后点击无反应：GUI 启动期可能被重依赖阻塞；将重依赖延迟到"开始导出"再 import；添加日志排查。
Nuitka + MinGW 在非 ASCII 路径报错：把源码复制到 ASCII 目录再编译；设置 PYTHONIOENCODING=utf-8。
Inno Setup 警告 x64 已弃用（仅 64 位构建需要 64 位安装模式时）：改为 ArchitecturesInstallIn64BitMode=x64compatible；32 位构建无需此项。
--disable-console 已废弃：改用 --windows-console-mode=disable。
dist 出现 _nuitka_temp.exe：在 [Files] 中排除它。

优化效果预期

优化组合	体积减少	启动提升	风险等级
基础编译	基准	基准	无
+ `--lto=yes`	5-10%	10-20%	PASS: 无
+ anti-bloat	15-25%	-	PASS: 无
+ 模块排除	20-35%	5%	PASS: 无
+ dist 瘦身	25-40%	-	PASS: 无
+ 32 位编译	40-60%	-	PASS: 无
全部组合	45-65%	15-25%	PASS: 无风险

WARNING: 不建议使用 UPX 压缩，虽然能进一步减小体积，但极易触发杀毒软件误报。

基于参考项目实战经验优化，助你打造商业级安装包！

generating-python-installer

More from this repository

Generating Python Installer (Commercial-Grade)

When to Activate

How It Works

Examples

核心理念

实战参考案例（生产级 PySide2 桌面应用，323 MB，含 OpenCV / Playwright）

项目概况

关键优化策略

体积分布

预期效果对比

核心工作流 (Workflow) - WARNING: 严格执行

Nuitka 极限优化编译（基于 参考项目经验）

一、32 位 vs 64 位选择策略

二、模块排除清单（参考项目验证过的）

三、GUI 框架专用优化

Tkinter 极限优化（推荐，最轻量）

PyQt5 / PySide2 优化

四、一键编译脚本模板

五、dist 瘦身脚本（参考项目级别清理）

六、DLL 依赖分析工具

完整优化工作流

步骤 1：修改编译脚本配置

步骤 2：一键编译+瘦身

步骤 3：分析 DLL 依赖

步骤 4：根据分析结果优化

VC++ 运行库处理方案

方案一：静态链接（推荐）

方案二：捆绑运行库安装（商业发布推荐）

Inno Setup 脚本模板（商业终极版）

占位符说明

常见问题 (FAQ)

Q1: 安装后双击程序无反应？

Q2: 安装包体积过大？

Q3: 杀毒软件误报？

Q4: 安装时提示 Windows 已保护你的电脑？

实战问题处理记录（更新 2026-02-07）

优化效果预期

Generating Python Installer (Commercial-Grade)

When to Activate

How It Works

Examples

核心理念

实战参考案例（生产级 PySide2 桌面应用，323 MB，含 OpenCV / Playwright）

项目概况

关键优化策略

体积分布

预期效果对比

核心工作流 (Workflow) - WARNING: 严格执行

Nuitka 极限优化编译（基于 参考项目经验）

一、32 位 vs 64 位选择策略

二、模块排除清单（参考项目验证过的）

三、GUI 框架专用优化

Tkinter 极限优化（推荐，最轻量）

PyQt5 / PySide2 优化

四、一键编译脚本模板

五、dist 瘦身脚本（参考项目级别清理）

六、DLL 依赖分析工具

完整优化工作流

步骤 1：修改编译脚本配置

步骤 2：一键编译+瘦身

步骤 3：分析 DLL 依赖

步骤 4：根据分析结果优化

VC++ 运行库处理方案

方案一：静态链接（推荐）

方案二：捆绑运行库安装（商业发布推荐）

Inno Setup 脚本模板（商业终极版）

占位符说明

常见问题 (FAQ)

Q1: 安装后双击程序无反应？

Q2: 安装包体积过大？

Q3: 杀毒软件误报？

Q4: 安装时提示 Windows 已保护你的电脑？

实战问题处理记录（更新 2026-02-07）

优化效果预期

More from this repository

Nuitka 极限优化编译（基于参考项目经验）

Nuitka 极限优化编译（基于参考项目经验）