Pyinstaller windows distribution

功能本地化（线下）部署 —— Python 脚本打包为 Windows 可执行分发包

将 Python 脚本打包为同事双击即可运行的 Windows exe，并整理成清晰的分发包结构。

核心流程

1. 用 PyInstaller 打包 exe

# 基础打包（单文件）
python -m PyInstaller --onefile --name "程序名称" your_script.py

# 打包并嵌入资源文件（Windows 用 ; 分隔）
python -m PyInstaller --onefile --name "程序名称" --add-data "config.html;." your_script.py

# 打包 Playwright/Chromium 等浏览器
python -m PyInstaller --onefile --name "程序名称" --add-data "chromium-1067;chromium-1067" your_script.py

关键参数：

• --onefile：打包成单个 exe 文件
• --name：exe 文件名
• --add-data "源路径;目标路径"：将额外文件/文件夹嵌入 exe（Windows 用 ;，Mac/Linux 用 :）
• --windowed：无控制台窗口（GUI 程序用）
• --icon=app.ico：自定义图标

2. 在代码中读取嵌入资源

PyInstaller 运行时会把资源解压到临时目录，用 sys._MEIPASS 获取路径：

import sys, os

def resource_path(relative_path):
    """获取资源路径，兼容开发模式和 PyInstaller 模式"""
    if hasattr(sys, '_MEIPASS'):
        return os.path.join(sys._MEIPASS, relative_path)
    return os.path.join(os.path.abspath("."), relative_path)

CONFIG_HTML = resource_path("config.html")

3. 制作 bat 启动脚本

bat 文件是 Windows 用户最熟悉的入口。必须注意以下坑：

a) 必须用 CRLF 换行（\r\n）

用 Python 的 Write 工具直接写 bat 会得到 LF 换行，cmd.exe 会静默失败。正确写法：

bat_content = "@echo off\r\nchcp 65001 >nul\r\nset \"PROG_DIR=%~dp0_internal\"\r\n\"%PROG_DIR%\\程序.exe\"\r\npause\r\n"
with open("启动.bat", "w", encoding="utf-8", newline="\r\n") as f:
    f.write(bat_content)

b) 文件夹名必须是纯 ASCII

中文全角括号 （） 会被 cmd.exe 当作语法字符解析，导致 bat 静默失败。

• ❌ 程序文件（勿删）
• ✅ _internal
• ✅ app_files

c) 标准 bat 模板

@echo off
chcp 65001 >nul
set "PROG_DIR=%~dp0_internal"
set "PLAYWRIGHT_BROWSERS_PATH=%PROG_DIR%"
"%PROG_DIR%\程序.exe"
echo.
echo 程序已退出。
pause

4. 整理分发包文件夹结构

目标：用户打开文件夹后，一眼就知道该点哪个。

我的工具1.0/
├── 启动工具.bat          ← 清晰入口 1
├── 查看报表.bat          ← 清晰入口 2
├── 运行说明.txt          ← 清晰入口 3
└── _internal/            ← 隐藏的程序文件
    ├── 程序.exe
    ├── chromium-1067/    ← 浏览器等依赖
    └── ...

隐藏 _internal 文件夹：

attrib +h "_internal"

5. 常见踩坑清单

问题现象	根因	解决
双击 bat 无任何反应	bat 文件是 LF 换行	用 newline='\r\n' 写入
双击 bat 闪退/报错	文件夹名含中文全角括号 （）	改为纯 ASCII 如 _internal
exe 找不到 Chromium	Playwright 浏览器未打包	--add-data 嵌入 + find_chromium() 多路径查找
exe 运行时找不到 config.html	资源路径未用 sys._MEIPASS	用 resource_path() 包装
exe 复制时提示 "设备忙"	旧 exe 进程仍在运行	taskkill /f /im 程序名.exe
路径含中文导致读取失败	某些库对中文路径支持差	把资源文件复制到 tempfile.gettempdir() 再读取

6. 带 Playwright 的完整打包示例

# find_chromium.py — 多路径查找浏览器
def find_chromium():
    import sys, os
    # 1. PyInstaller 临时目录
    if hasattr(sys, '_MEIPASS'):
        bundled = os.path.join(sys._MEIPASS, "chromium-1067", "chrome-win", "chrome.exe")
        if os.path.exists(bundled):
            return bundled
    # 2. exe 同级目录
    app_dir = os.path.dirname(sys.executable if getattr(sys, 'frozen', False) else __file__)
    portable = os.path.join(app_dir, "chromium-1067", "chrome-win", "chrome.exe")
    if os.path.exists(portable):
        return portable
    # 3. 系统安装的 Playwright
    candidates = [
        os.path.expandvars(r"%LOCALAPPDATA%\ms-playwright\chromium-1067\chrome-win\chrome.exe"),
    ]
    for path in candidates:
        if os.path.exists(path):
            return path
    return None

# main.py 中使用
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    chromium_path = find_chromium()
    browser = p.chromium.launch(
        headless=False,
        executable_path=chromium_path,
        args=["--start-maximized"]
    )

打包命令：

python -m PyInstaller --onefile --name "我的工具" \
  --add-data "config.html;." \
  --add-data "chromium-1067;chromium-1067" \
  main.py

质量检查清单

打包完成后验证：

• 在未安装 Python 的电脑上测试运行
• 验证 bat 文件双击能正常启动
• 验证资源文件（html、配置文件）能被正确读取
• 如有浏览器依赖，验证浏览器能正常启动
• 文件夹结构清晰，非技术人员能一眼找到入口