必须确认platform标识匹配，Python C扩展二进制兼容性依赖sysconfig.get_platform()输出而非系统名称；macOS ARM64上用Intel Python编译会导致Symbol not found或段错误；交叉编译需匹配对应平台编译器、解释器及MACOSX_DEPLOYMENT_TARGET；setup.py中应基于sys.platform和platform.machine()条件配置，避免硬编码；wheel平台标签由构建环境和auditwheel/delvewheel等工具决定，非手动修改setup.cfg可控制。
编译前必须确认平台标识是否匹配
Python C扩展的二进制兼容性高度依赖 platform 和 sysconfig.get_platform() 的输出，而不是你“以为”的系统名。比如在 macOS ARM64 上用 Intel Python（x86_64 构建）编译的模块，即使能 import，运行时大概率报 Symbol not found 或直接段错误。
- 运行
python -c "import sysconfig; print(sysconfig.get_platform())"—— 这才是 setuptools 和pyproject.toml中setup.py实际参考的平台字符串 - 交叉编译时（如在 Linux 上编译 Windows 模块），不能只靠
--plat-name参数覆盖；必须配合对应平台的编译器（如x86_64-w64-mingw32-gcc）和 Python 解释器（如python3.11-win-amd64.exe） - macOS 上注意
MACOSX_DEPLOYMENT_TARGET环境变量必须与目标 Python 的构建目标一致（常见值为10.9、11.0或12.0），否则ld: library not found for -lc++
setup.py 里 platform-specific 编译选项怎么写才生效
setup.py 中的 Extension 构造函数本身不感知平台，真正起作用的是 build_ext 命令的参数传递路径和编译器调用时机。硬编码 extra_compile_args 很容易在非目标平台触发编译失败。
- 用
sys.platform+platform.machine()做条件分支，而不是靠文件名或环境变量猜测：例如if sys.platform == "win32" and platform.machine() == "AMD64" - Windows 下启用
/MD（动态链接 CRT）是默认行为，但若你的 C 库是静态链接的，就得显式加extra_link_args=["/MT"]，否则运行时报MSVCP140.dll not found - Linux 上避免直接写
-march=native—— 它会让生成的 .so 在老 CPU 上报Illegal instruction；改用-march=x86-64-v3或保守的-march=x86-64
pyproject.toml 中如何控制 wheel 的 platform tag
PEP 600 后 wheel 的平台标签（如 cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64）不由源码决定，而由构建环境和 auditwheel / delvewheel 工具重写。手动改 setup.cfg 的 [bdist_wheel] 段几乎无效。
创建 Flask + Vue.js 全栈项目，采用单端口架构、uv 依赖管理、结构化日志和生产级前端设计。当用户要求以下操作时触发：创建新的 Flask+Vue 项目、搭建 Web 应用、构建全栈 Python+Vue 应用、初始化 Flask Web 项目、设置单端口 Flask 前后端项目。触发词：新建项目、创建项目、搭建项目、Flask项目、Vue项目。
- Linux：用
auditwheel repair dist/*.whl重打标签，它会扫描.so依赖并自动选最保守的 manylinux tag - Windows：用
delvewheel repair dist/*.whl，它会把缺失的 DLL 打包进去，并修正win_amd64或win_arm64标签 - macOS：
delocate repair dist/*.whl处理 dylib 路径，但平台标签仍需匹配sysconfig.get_platform()输出（如macosx_12_0_arm64）
本地测试时最容易忽略的 ABI 兼容陷阱
很多开发者在本机成功编译后就认为没问题，结果部署到目标机器上 import 失败——问题往往出在 ABI 层级的隐式依赖上，而非 Python 版本或平台字符串。
- 用
objdump -T your_module.cpython-*.so | grep Py（Linux/macOS）或dumpbin /exports your_module.pyd（Windows）检查是否链接了正确的 Python ABI 符号（如PyModule_Create对应的版本号） - Linux 上运行
ldd -r your_module.cpython-*.so，确认所有依赖库（尤其是libpython3.11.so）路径可解析，且没出现undefined symbol - macOS 上特别注意
@rpath设置：如果 C 扩展依赖第三方 dylib，必须用install_name_tool -add_rpath @loader_path/../libs显式声明，否则ImportError: dlopen(...): Library not loaded
平台特定编译不是“换个命令就行”，关键在于让 Python 解释器、C 编译器、链接器和打包工具对 ABI 达成一致理解——任何一环 mismatch，都会在 import 那一刻才暴露。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
