Python 脚本打包成全局 CLI（pyproject + console_scripts 入口点）

2026-08-13 暂无评论

把散在某个目录的 xxx.py 脚本，通过打包变成任意目录下都能直接调用的全局命令（如 imagegen "prompt"），而不用每次敲 python xxx.py。

目标

任意工作目录下直接调用全局命令，不再需要 python <脚本路径> ...
卸载干净（pip uninstall 即移除）
脚本仍保留"纯透传"逻辑，不引入依赖

前置条件

Python 3.8+，pip 可用
本地 setuptools >= 61（pip show setuptools 查看）

步骤

在脚本所在目录创建 pyproject.toml：

[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"

[project]
name = "imagegen"
version = "0.1.0"
description = "AI 生图 CLI：自定义 API 配置，指定输出路径与提示词"
requires-python = ">=3.8"

[project.scripts]
imagegen = "generate:main"        # 命令名 = "模块名:函数名"

[tool.setuptools]
py-modules = ["generate"]         # 单文件模块要显式声明，否则不会被包含

脚本本身结构：generate.py 顶部不能有 if __name__ == "__main__" 之外的副作用，入口函数 main() 必须是模块级函数。
editable 安装（避免走网络，用本地 setuptools）：
```
python -m pip install -e . --no-build-isolation
```

验证：

imagegen --help        # 命令存在于 Scripts 目录：python -m site 查 Scripts 路径

关键点与坑

entry point 语法：[project.scripts] 里 命令名 = 模块:函数，不是路径。
单文件模块必须声明：只有 .py 文件时 [tool.setuptools] py-modules = ["xxx"] 必不可少，否则装完发现模块没被打包。
editable 与 __file__：pip install -e . 后 __file__ 仍指向源目录，因此脚本里"用 __file__ 定位同目录配置文件"（如 configs.json）的逻辑不受影响。
--no-build-isolation：本地 setuptools 版本够新时，用它跳过 pip 去 PyPI 拉取构建依赖，中国大陆网络下更快更稳。
Windows 下乱码：脚本用 UTF-8 打印中文，在 Git Bash 里可能显示成乱码（GBK 终端），属于终端编码问题，不影响功能；在 cmd/PowerShell 可正常。
命令是否在 PATH：生成的 exe 在 C:\Users\...\Python311\Scripts，需确保该目录在 PATH。