使用PyInstaller构建的Python可执行文件（误当作pyz）在Mac运行时出现UTF-8编码语法错误

看起来你碰到了两个容易混淆的核心问题，咱们一步步拆解来解决：

1. 先搞懂：你生成的不是pyz，是Linux原生可执行文件 #

敲黑板划重点：PyInstaller在Ubuntu（Linux）环境下构建出来的文件，是Linux专属的二进制可执行文件，根本不是你以为的pyz（Python zip归档包）。

你拿这个Linux二进制文件到Mac上，用python3 test.pyz去运行，相当于让Python解释器去解析一堆Linux机器码字节——这些字节里肯定有大量非UTF-8的内容（比如你看到的\xb9），Python把它当成Python代码解析，自然就触发了PEP-263的编码错误。这才是问题的根源！

2. 解决跨平台运行问题：PyInstaller必须“在哪用，在哪建” #

PyInstaller是强平台绑定的工具：

• Linux环境只能构建Linux能用的可执行文件
• Mac环境（Intel/Apple Silicon）才能构建对应架构的Mac可执行文件
• Windows同理

所以如果你要给Mac用户分发，必须在Mac环境里重新构建：

• 本地用Mac电脑，安装Poetry和PyInstaller，重复你的构建命令
• 或者在CI/CD里加Mac构建环节（比如GitHub Actions的macos-latest runner），自动生成Mac版本的可执行文件

3. 要是后续在Mac构建仍有编码问题，这些点可以排查 #

如果在Mac上构建后还是碰到编码相关错误，可以检查这些细节：

• 确保**所有Python源码文件（包括你的test_pyz.spec）**开头都加了编码声明：# -*- coding: utf-8 -*-，不要漏了任何一个被打包的文件
• 构建前设置系统级编码环境变量：

  export LC_ALL=en_US.UTF-8
  export LANG=en_US.UTF-8
  poetry run pyinstaller test_pyz.spec --noconfirm --distpath build/pyz
  

• 检查项目里的资源文件：有没有引入GBK/GB2312等非UTF-8编码的配置、文本文件？如果有，要么转成UTF-8，要么在读取时显式指定编码

4. 如果你确实想做跨平台的pyz包：别用PyInstaller #

如果你的目标是生成一个能在多平台用python3 xxx.pyz直接运行的归档包，那应该用Python自带的zipapp模块，而不是PyInstaller：

# 假设你的项目入口是main.py里的main函数
python3 -m zipapp your_project -m "main:main"

生成的.pyz文件可以在任何装有对应Python版本的平台上直接运行，不需要跨平台构建。

备注：内容来源于stack exchange，提问作者Andre Gagne