科技 · 实用指南
Python 报“.pyc bad magic number”？先证明运行时与源码边界
不要先删光缓存或修改文件头；先确认 Python 实际加载的文件、正在运行的解释器，以及可用源码是否存在。
不要先删光缓存或修改文件头；先确认 Python 实际加载的文件、正在运行的解释器，以及可用源码是否存在。
pyc header 以解释器特定的 magic bytes 开头。 importlib.util.MAGIC_NUMBER 给出当前解释器值。
1. 记录失败文件与解释器
清理前保存完整 traceback，记录 sys.executable、sys.version、sys.implementation.cache_tag、工作目录、导入相关环境变量和失败模块路径。shell 里的 python 不一定是服务、IDE、任务或嵌入程序实际使用的解释器。
根据 traceback 或导入发现定位准确文件，检查 sys.path 顺序、虚拟环境、挂载卷和复制的部署目录。此错误证明字节码不兼容，不代表机器上所有 pyc 都错误。
2. 只读比较文件头
把可疑文件当数据打开，只读前四个字节，并与真正失败解释器的 importlib.util.MAGIC_NUMBER 比较。不要为检查而导入或执行不可信字节码。
不匹配可证明该文件不是此解释器构建的字节码；匹配也不是安全或完整性证明，剩余 header、marshal 代码或源码关系仍可能无效或损坏。
3. 区分有源码与仅 pyc
若权威 .py 源码存在，先保存旧 pyc 证据，只删除准确的不兼容缓存，让目标解释器重新生成。再确认进程可写缓存目录；没有生成新 pyc 本身不等于导入失败。
若部署仅含 pyc，删除它等于删除程序，不能刷新缓存。向所有者取得源码或用目标解释器重建；不要改 magic bytes 强行加载，因为 opcode 与 marshal 格式也可能不同。
4. 生成或重建正确产物
已安装包要对照包元数据，并从可信 wheel 或源码在干净环境重建或重装。PyPA 说明 wheel 通常不包含 pyc，而由安装器在本地生成，因此产物里的外来缓存是打包线索。
容器和 serverless 包应在生产准确运行时下从干净上下文重建，排除宿主机 __pycache__，解释器升级后不要复用挂载缓存。
5. 验证导入并防止复发
用真实入口重启并核对同一 executable、import origin 与模块版本。在新进程验证代表性导入，再确认生成缓存的路径和 tag 符合目标运行时。
记录失败路径、新旧 magic bytes、运行时身份、源码状态、重建来源和验证结果。加入干净构建测试，除非兼容性被明确证明，否则拒绝 pyc-only 或外来缓存产物。
