setup.py读取含中文文件时因未指定encoding参数导致UnicodeDecodeError，根本原因是Python默认编码与文件实际编码（如GBK）不匹配；应显式指定encoding='utf-8-sig'或'gbk'，优先将文件转为UTF-8保存。
setup.py读取文件时抛出UnicodeDecodeError
Python 2默认用ASCII解码，Python 3默认用UTF-8，但Windows系统上很多setup.py会读取README.md或__init__.py等含中文的文件，而这些文件实际是GBK编码——此时open()不指定encoding就会崩在read()那行，报错类似：UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc4 in position 10。
根本原因不是setup.py本身有问题，而是它调用open()读取项目元数据时没传encoding参数，让Python按平台默认编码去猜，一猜就错。
- 检查出问题的文件真实编码：用VS Code或Notepad++打开
README.md，右下角看是UTF-8、GBK还是UTF-8 with BOM - 在
setup.py里所有open()调用处显式加encoding参数，别依赖默认值 - 不要写
open('README.md', 'r', encoding='utf-8')硬编码UTF-8——如果文件是GBK，这行照样报错；优先用encoding='utf-8-sig'兼容BOM，或根据文件实际编码选'gbk'
setup()中long_description字段的编码处理
setup()函数的long_description参数通常来自readme文件内容，这是最常翻车的地方。错误写法：long_description=open('README.md').read()——完全没指定编码，跨平台必挂。
正确做法是统一用io.open()（兼容Py2/Py3）或Python 3.7+原生open()，并强制指定encoding：
立即学习“Python免费学习笔记（深入）”；
import io
with io.open('README.md', encoding='utf-8') as f:
long_description = f.read()
如果你确认README.md是Windows记事本保存的（即GBK），就得写encoding='gbk'；若不确定，可先用chardet探测：
import chardet
with open('README.md', 'rb') as f:
raw = f.read()
encoding = chardet.detect(raw)['encoding'] or 'utf-8'
with open('README.md', encoding=encoding) as f:
long_description = f.read()
使用setuptools.find_packages()时的中文路径问题
当包目录名或__init__.py路径含中文（比如src/工具模块/），find_packages()本身不报错，但后续构建wheel或sdist时，MANIFEST.in或setup.cfg若未声明编码，打包工具可能在读取文件列表时出错。
这不是find_packages()的锅，而是setup.py里其他open()调用没处理好。重点检查：
-
MANIFEST.in是否被open()读取？如有，必须加encoding - 自定义
build_py或sdist命令类时，所有open()都要带encoding - 避免在
setup.py里拼接中文路径字符串再传给os.listdir()或glob.glob()——它们返回的bytes或str类型在不同Python版本行为不一致
pyproject.toml替代setup.py后还用管encoding吗
用pyproject.toml后，setup.py可以删掉，但long_description仍可能从文件读取——比如用setuptools-scm或自定义dynamic字段。这时读取逻辑仍在Python代码里，encoding问题照旧存在。
例如，在pyproject.toml中这样写是危险的：
[project] readme = "README.md"
因为底层仍会调用open()读取该文件。最新版setuptools（≥61.0）已默认用utf-8读取readme，但如果你的README.md是GBK，就得在pyproject.toml里显式声明：
[project]
readme = {file = "README.md", content-type = "text/markdown; charset=gbk"}
不过这个charset字段支持度有限，更稳妥的方式仍是把README.md转成UTF-8保存——编辑器里“另存为”，编码选UTF-8，BOM勾不勾都行（utf-8-sig能自动跳过BOM）。
真正容易被忽略的是：即使迁移到pyproject.toml，只要代码里还有open()读文件，encoding就得自己管。没人替你兜底。
