应明确写出PHP兼容的完整版本范围，如"php": ">=8.0.0 <9.0.0"，而非仅"^8.1"，否则会错误排除实际兼容的8.0、8.2+等版本用户。
composer.json 里写清楚 php 版本范围，别只写 ^8.1
扩展包的 composer.json 中 "require": {"php": "..."} 字段不是摆设——它直接决定哪些项目能装你的包。只写 "^8.1" 会把 PHP 8.0、8.2、8.3 甚至 8.4+ 的用户全拦在外面，哪怕你的代码本身完全兼容。
真正可行的做法是用版本交集语法，比如：
"require": {
"php": "^8.0 || ^8.1 || ^8.2 || ^8.3 || ^8.4"
}
或者更简洁地写成："php": ">=8.0.0 （前提是确认没用 PHP 9 新特性）。
- 别依赖
config.platform.php来“伪装”版本——那是给下游项目用的，不是你扩展包自己该干的事 - 如果用了 PHP 8.3 的
match或 8.4 的enum，就得明确写^8.3起步，硬性卡住下限 - PHP 7.x 已 EOL，除非维护老项目，否则不建议再向下兼容
autoload 和测试必须覆盖多个 PHP 版本
PSR-4 自动加载本身不挑 PHP 版本，但一旦你用了 #[Attribute]、readonly class 或联合类型注解（如 string|int），低版本 PHP 就会在解析时直接报 ParseError，连 autoload 都进不去。
立即学习“PHP免费学习笔记（深入）”；
所以：
- 在
src/里避免混用高版本语法；若必须用，就用class_alias()或运行时特征检测兜底 - CI 测试至少跑
php:8.0、php:8.2、php:8.4三档（GitHub Actions 或 GitLab CI 都支持矩阵构建） - 别只测
composer install成功——要实际require 'vendor/autoload.php'并跑单元测试，否则 autoload_static.php 生成差异导致的运行时失败会被漏掉
不要在扩展包里调用 phpversion() 或 extension_loaded() 做硬分支
有些开发者习惯在服务类构造函数里写 if (version_compare(PHP_VERSION, '8.2', '>=')) { ... }，这看似灵活，实则埋雷：Composer 安装阶段不执行这些代码，但下游项目一 require 就崩，且错误堆栈极难定位。
更稳妥的方式是：
- 用
function_exists()或interface_exists()替代版本判断（比如检查str_contains()是否存在，而不是查 PHP 版本） - 把行为差异抽成独立 trait 或 adapter 类，让使用者按需组合，而不是在扩展包内部做“自动适配”
- 如果真要分发不同版本逻辑，用 Composer 的
replace+conflict分包策略，比如your/package-php82和your/package-php84，由下游项目显式选择
vendor/autoload.php 不是跨版本安全的，别指望复用
很多人以为只要扩展包代码兼容多版本，生成的 vendor/autoload.php 就能通用——错。Composer 会根据当前 PHP 版本的反射能力、类加载顺序、opcache 启用状态等，生成不同的 autoload_static.php 和 autoload_classmap.php。
这意味着：
- 你在 PHP 8.2 下
composer install出来的vendor/，放到 PHP 8.4 环境里可能因__serialize()方法签名变化而失效 - 扩展包发布时，
vendor/目录绝不能打包进去——它只属于消费者项目，不是你包的一部分 - 如果你提供 demo 项目或测试脚本，每个 PHP 版本都得单独
rm -rf vendor composer.lock && composer install，不能共用 lock 文件
最常被忽略的一点：即使你的扩展包本身没出问题，下游项目用了 "platform": {"php": "8.3"} 却在 PHP 8.1 上运行，autoload 失败时根本不会报“PHP 版本不对”，而是静默失败或抛出 Class not found——因为 Composer 早已在 install 阶段“假装”过了。
