VisiData 的 Windows 安装包构建全流程:WinPython + PyInstaller + Inno Setup 实战
VisiData 的 Windows 安装包构建全流程:WinPython + PyInstaller + Inno Setup 实战
VisiData(终端下的多维表格工具)本身是跨平台 Python 程序,但要在 Windows 上把它交付给「没有 Python 环境」的普通用户,就需要产出一个独立的 .exe 安装包。本文以仓库中的 vdwin-installer.md 为操作主线,完整讲解「WinPython 便携环境 → pip 安装 VisiData → PyInstaller 打包单文件 exe → Inno Setup 编译 setup 安装程序」的构建链路,并结合作品自带的 vdwin.py、vdwin.spec 与 setup.py 源码,说明每一步的底层原因与可验证依据。读完你既能照单复现 Windows 安装包,也能理解为何 Windows 打包比 Linux/macOS 多出 curses 与图标这两道工序。
为什么 Windows 版需要专门的打包方案
VisiData 是终端界面程序,交互层依赖 curses。在 Linux/macOS 上 curses 是系统自带库,但 Windows 的 Python 标准库并不包含 curses,必须借助第三方包 windows-curses 补齐。这一点在 setup.py 中有明确实现:
if not sysconfig.get_platform().startswith("mingw"): # 2757
install_requires += ['windows-curses >= 2.4.1; platform_system == "Windows"'] # 2119
也就是说,VisiData 本体在 pip 安装时就会针对 Windows 平台自动引入 windows-curses(最低 2.4.1,对应 issue #2119;同时排除 MSYS2/mingw 环境,对应 issue #2757)。而 vdwin(VisiData on Windows)这套安装包方案解决的是更进一步的问题:让最终用户无需安装 Python、无需打开命令行执行 vd,直接双击即可运行。仓库根目录的 README.md 将 VisiData 定位为 "terminal spreadsheet multitool",Windows 安装包正是把这一工具以桌面软件形态交付给终端用户的桥梁。
此外,从 setup.py 可确认项目要求 python_requires=">=3.8",因此打包所选用的 WinPython 发行版只要内置 Python 3.8 及以上即可,原文档示例采用 WinPython 的 python-3.9.4.amd64 完全满足要求。
第一步:准备 WinPython 便携环境
原文档给出的第一条命令是安装 WinPython:https://winpython.github.io/。
选择 WinPython 而非系统级 Python 安装包,原因很实际:
- 免管理员权限:WinPython 是绿色便携发行版,解压即用,适合在 CI 或隔离构建机上打包;
- 自带 Scripts 目录:解压后的目录形如
WinPY\python-3.9.4.amd64,其中Scripts下直接就有pip3.exe、pyinstaller.exe等命令行工具,后续所有命令都以./Scripts/xxx.exe形式调用; - 版本可控:与 VisiData 要求的
python_requires=">=3.8"(见 setup.py)可精确对齐,避免宿主机器 Python 版本漂移导致打包产物不可用。
下载并解压后,在 PowerShell 或 CMD 中进入该目录:
cd WinPY\python-3.9.4.amd64
后续所有 ./Scripts/... 命令均在此目录下执行。
第二步:安装 VisiData 本体
在 WinPython 环境中安装发布版 VisiData:
./Scripts/pip3.exe install visidata
该命令从 PyPI 拉取 visidata 及其依赖(如 python-dateutil,见 setup.py 的 install_requires)。安装完成后,Windows 下会注册 vd 与 visidata 两个命令行入口——它们在 setup.py 中通过 entry_points 声明:
entry_points={
"console_scripts": ["vd=visidata.main:vd_cli",
"visidata=visidata.main:vd_cli"],
},
两者都指向 visidata/main.py 中的 vd_cli(),即 VisiData 的统一 CLI 入口。
安装 develop 开发版(可选)
如果需要跟踪开发分支(对应本仓库 3.5dev 的开发版本线,见 setup.py),原文档给出两条附加命令:
- 安装 Git for Windows:https://git-scm.com/download/win(提供
git命令及 pip 的 git 协议安装支持); - 从 develop 分支直接安装源码:
./Scripts/pip3.exe install git+https://github.com/saulpw/visidata.git@develop
pip 会先克隆该 git 仓库,再以本地源码方式执行 setup.py 完成安装。需要留意的是:开发分支是持续变动的,产物稳定性不如 PyPI 发布版,只建议在调试新特性、复现开发版缺陷时使用。若后续还想回到稳定版,用 ./Scripts/pip3.exe install -U visidata 即可覆盖回 PyPI 版本。
第三步:补齐 Windows 终端依赖 windows-curses
./Scripts/pip3.exe install windows-curses
虽然第二步安装 visidata 时,setup.py 的条件依赖机制理论上会自动带上 windows-curses,但原文档仍显式执行此步。原因在于:
- 兜底保证:如果 pip 解析条件依赖失败、或使用了不经过 setup.py 依赖声明的安装方式(如直接克隆源码运行),显式安装可确保 curses 层可用;
- PyInstaller 打包需要:打包时 PyInstaller 需要能实际导入
windows-curses提供的_curses扩展模块才能将其收进产物,显式安装能减少 hidden import 遗漏的风险。
VisiData 在 Windows 上若缺少该包,启动时会在初始化 curses 界面处直接报错,因此这是打包前必须验证的一环。
第四步:安装 PyInstaller
./Scripts/pip3.exe install pyinstaller
PyInstaller 负责把 Python 解释器、VisiData 代码与全部依赖冻结成 Windows 可执行文件。它有两个典型产物模式:
--onefile:所有内容合并进单个 exe,便于分发,但启动时会先解压到临时目录,首启略慢;- 默认 one-dir 模式:生成一个包含 exe 与依赖 dll/库文件的目录,启动快,但需要整目录分发。
本仓库的 vdwin.spec 就是 PyInstaller 的 one-dir 模式配置(含 Analysis / PYZ / EXE / COLLECT 四段标准结构),它与命令行参数是同一打包引擎的两种表达方式,可作为理解 PyInstaller 内部结构的参考。
第五步:获取 vdwin 启动器与图标
原文档要求克隆 Windows 启动器项目:
git clone https://github.com/saulpw/vdwin.git WinPy/vdwin
vdwin 项目为 Windows 打包提供两样东西:
- 启动脚本(原文档中名为
visidata.py):一个极薄入口,其职责等价于本仓库 platform/windows/vdwin.py 的实现:
from visidata.main import vd_cli
from visidata import vd
vd_cli()
也就是导入 visidata/main.py 的 vd_cli() 并调用,与仓库自身的 python -m visidata 入口(见 visidata/main.py)行为一致。之所以需要一个独立脚本,是为了给 PyInstaller 一个明确的「程序入口文件」,让打包器能顺着 import 链收集全部依赖。
- 应用图标:
vdicon.ico。本仓库 platform/windows/vdicon.ico 即是该图标文件(256×256),打包时通过--icon参数嵌入 exe,让生成的程序在资源管理器里显示 VisiData 自己的图标而非 Python 默认图标。
第六步:用 PyInstaller 生成单文件 exe
核心打包命令:
./Scripts/pyinstaller.exe --onefile/-F --icon/-i ..\vdwin\vdicon.ico --name/-n VisiData ..\vdwin\visidata.py
参数逐一说明:
| 参数 | 简写 | 作用 |
|---|---|---|
--onefile |
-F |
生成单文件 exe,用户拿到一个文件即可运行 |
--icon ..\vdwin\vdicon.ico |
-i |
把 vdicon.ico 嵌入 exe 作为程序图标 |
--name VisiData |
-n |
指定输出程序名为 VisiData.exe |
| 末尾的脚本路径 | — | 指定打包入口,即 vdwin 项目中的 visidata.py(本仓库对应 platform/windows/vdwin.py) |
原文档给出的产物路径是:
dist/visidata/visidata.exe
具体路径形态取决于打包模式与 --name:--onefile 模式下通常得到 dist\VisiData.exe 单文件;若参考本仓库 vdwin.spec 的 one-dir 写法(name='VisiData' + COLLECT),则会得到 dist\VisiData\VisiData.exe 目录形态。无论哪种形态,验证标准一致:双击能正常启动 VisiData 界面。首次启动建议在命令行中运行以观察 stderr 输出,若提示缺模块,说明存在 hidden import 问题,需要在 spec 文件的 hiddenimports 中补充(vdwin.spec 中该项为空,即当前依赖收集已足够)。
第七步:用 Inno Setup 编译 VisiData-setup.exe
Inno Setup Compiler (6.1.2)
vd.iss
PyInstaller 产出的是免安装的绿色 exe,而面向普通用户的正式交付通常需要一个「安装向导」。这一步用 Inno Setup Compiler 6.1.2 打开 vdwin 项目提供的 vd.iss 脚本并编译:
vd.iss是 Inno Setup 的安装脚本(此脚本由外部 vdwin 项目维护,不在本仓库内;*.iss在本仓库无匹配文件),其中会声明安装程序名称(对应VisiData-setup.exe)、许可协议、安装目录(如%LocalAppData%\Programs\VisiData或 Program Files)、开始菜单快捷方式等;- 编译前需要在脚本的
[Files]段把Source指向第六步生成的 exe 路径,例如dist\VisiData.exe或dist\VisiData\VisiData.exe; - 编译产物
VisiData-setup.exe即为最终可分发的安装包,用户双击后经向导完成安装并生成快捷方式。
Inno Setup 与 PyInstaller 的分工可以概括为:PyInstaller 负责「把 Python 程序变成 Windows 程序」,Inno Setup 负责「把 Windows 程序变成带安装向导的正式软件包」。
构建流程总览与验证清单
完整链路如下:
WinPython 便携 Python
│ ./Scripts/pip3.exe install visidata
│ ./Scripts/pip3.exe install windows-curses
│ ./Scripts/pip3.exe install pyinstaller
▼
vdwin 项目(visidata.py 入口 + vdicon.ico 图标)
│ pyinstaller --onefile --icon ..\vdwin\vdicon.ico --name VisiData ..\vdwin\visidata.py
▼
VisiData.exe(单文件/目录两种形态)
│ Inno Setup 打开 vd.iss 并编译
▼
VisiData-setup.exe(最终安装包)
打包完成后建议按以下清单验收:
- 依赖完整性:在 WinPython 中先直接运行
./Scripts/vd.exe sample.tsv(可用仓库 sample_data/sample.tsv 验证),确认 curses 界面正常,再做 PyInstaller 打包,可大幅减少「能 pip 运行、打包后却缺库」的返工; - 产物可启动:双击 exe,确认界面渲染、方向键移动、
q退出均正常; - 图标生效:exe 在资源管理器中显示 VisiData 图标(对应 vdicon.ico);
- setup 安装/卸载:在干净 Windows 环境(无 Python)安装
VisiData-setup.exe,验证普通用户开箱即用; - 版本与来源一致:发布版走 PyPI 安装、开发版走 develop 分支安装,二者不要混用,避免交付物行为与预期不符。
延伸:不打包也能用的替代方案
如果你的受众本身具备 Python 环境,其实无需整套打包流程,直接 pip install visidata 后使用 vd / visidata 命令即可(两个入口由 setup.py 注册)。打包方案的价值在于把终端工具「产品化」:用户无需接触命令行、无需理解 Python 依赖,双击安装包即可获得完整的 VisiData 体验——这正是 vdwin-installer.md 这份构建文档存在的意义。