python打包时编码错误主因是setup.py或pyproject.toml含非utf-8字符、readme.md带bom、toml字符串未引号、locale非utf-8；应统一转utf-8、去bom、显式指定encoding、字符串加双引号、设置正确locale。
setup.py 或 pyproject.toml 文件本身含非UTF-8字符
Python 3.7+ 默认要求源码文件为 UTF-8 编码，但 Windows 记事本、某些 IDE 或 Git 钩子可能悄悄存成 GBK/ISO-8859-1。一旦 setup.py 里有中文注释、作者名、描述字段用了非 UTF-8 字节，python -m build 或 python setup.py bdist_wheel 就会在解析阶段直接报错，比如：
SyntaxError: Non-UTF-8 code starting with '\xd6' in file setup.py
这不是依赖或环境问题，而是 Python 解释器读取脚本时就卡住了。
- 用
file setup.py（Linux/macOS）或chcp+more setup.py（Windows）确认实际编码 - 用 VS Code / PyCharm 打开后右下角看编码标识，点击切换并「Save with Encoding → UTF-8」
- 避免在
setup.py的setup()调用中硬写带中文的description或long_description；改用open("README.md", encoding="utf-8").read()
README.md 或其他被读取的文本文件含 BOM 或混合编码
很多项目在 setup.py 或 pyproject.toml 中通过 open("README.md") 读取内容填充 long_description。如果该文件是 Windows Notepad 保存的 UTF-8 with BOM，Python 3 默认 open() 会把 BOM 当作普通字符读入，导致生成的 METADATA 文件头部出现非法字节，后续 pip install 可能静默失败或报 InvalidDistribution。
- 检查 README.md 是否含 BOM：
head -c 3 README.md | xxd—— 输出00000000: efbb bf即为 BOM - 去除 BOM：用
sed -i '1s/^\xEF\xBB\xBF//' README.md（Linux/macOS），或用 VS Code 保存为「UTF-8」而非「UTF-8 with BOM」 - 在
setup.py中显式声明编码：open("README.md", encoding="utf-8")，不要省略encoding参数
pyproject.toml 中字符串值未加引号导致解析失败
TOML 规范要求含空格、中文、特殊符号的字符串必须用双引号包裹。若你在 [project] 下写了：
authors = [{name = 张三, email = "zhang@example.com"}]
这里 张三 没加引号，tomllib（Python 3.11+ 内置）或 tomli 会直接拒绝解析，报错类似：
tomllib.TOMLDecodeError: Invalid character '张'
注意：这个错误发生在构建前期（读取配置阶段），甚至不会走到编译或打包逻辑。
- 所有含中文、空格、连字符、点号的字符串值都必须加双引号，例如：
name = "张三" - 用
tomliCLI 验证：python -m tomli dump pyproject.toml，出错即说明格式不合法 - 避免在
[project.urls]或[project.optional-dependencies]的键名里使用中文——TOML 键名不支持 Unicode 转义以外的非 ASCII 字符
构建环境 locale 设置影响 open() 默认编码
在某些 Linux 容器或 CI 环境（如 Ubuntu base 镜像），LANG 可能是 C 或 POSIX，导致 open() 默认使用 locale.getpreferredencoding()（即 ASCII），而非 UTF-8。这时即使文件是 UTF-8，读取也会失败。
- 检查当前 locale：
locale，确认LANG和LC_ALL是类似en_US.UTF-8的值 - 在 CI 脚本中显式设置：
export LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 - 更稳妥的做法：所有
open()调用都强制指定encoding="utf-8"，不依赖系统默认
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
