swoole.use_shortname 必须显式设为 off，否则 hyperf 启动失败或协程不生效；需在对应 swoole.ini 中添加 swoole.use_shortname = off，并用 php --ri swoole 验证输出含 support coroutines: enabled 和 swoole.use_shortname => off。
swoole.use_shortname 必须显式设为 Off，否则 Hyperf 启动直接失败或协程不生效。
怎么确认当前是否已关闭
运行 php --ri swoole，检查输出中是否包含：
-
support coroutines: enabled（关键） -
swoole.use_shortname => Off（必须出现，不能是 On / 1 / true）
如果没看到 swoole.use_shortname => Off，或显示 On、1、空值、甚至根本没这一行，说明没关或配置未生效。
在哪改 php.ini 才真正生效
别只改主 php.ini —— Swoole 的配置常被单独拆到扩展配置文件里，比如：
-
/etc/php/8.2/cli/conf.d/20-swoole.ini（Ubuntu/Debian CLI） -
/usr/local/php/conf.d/swoole.ini（源码安装常见路径） -
/www/server/php/82/etc/php.d/swoole.ini（宝塔面板 PHP 8.2）
找到对应文件，在 extension="swoole.so" 下方添加或修改一行：
sudo echo "swoole.use_shortname = Off" >> /path/to/swoole.ini
改完后必须重启 PHP 进程（不是 reload）：
- FPM：执行
sudo systemctl restart php8.2-fpm或sudo service php-fpm restart - CLI 场景：无需重启，但要确保下次运行
php命令时加载的是新配置（可用php -c /path/to/php.ini --ri swoole验证）
为什么设成 0 或 'off' 都可能无效
Swoole 对这个配置项的解析很严格，只认明确的字符串 Off（首字母大写，全拼，无引号）：
- ❌
swoole.use_shortname = 0→ 被当作文本，实际等效于On - ❌
swoole.use_shortname = 'off'→ 单引号导致解析失败，值为空，等效于未设置 - ❌
swoole.use_shortname = false→ PHP 解析为布尔 false，Swoole 不识别 - ✅
swoole.use_shortname = Off→ 唯一稳定有效的写法
Hyperf 启动时若检测到短名开启，会拒绝初始化协程客户端（如 Co\MySQL、Co\Redis），哪怕你没主动用，底层日志、配置加载也依赖协程，最终表现为启动卡住、报错 Coroutine is not available 或直接退出。
常见连带问题：改了还是不生效
不是改错位置，就是被覆盖：
- CLI 和 FPM 使用不同
php.ini：用php --ini和php -i | grep 'Loaded Configuration File'分别查清楚 - 多个 swoole.ini 文件共存：比如同时有
20-swoole.ini和99-swoole-custom.ini，后者可能覆盖前者 - Docker 或容器环境：配置改在宿主机无效，必须进容器内修改并重启 PHP 进程
- 宝塔面板：可视化开关“关闭 Short Name”有时只写入默认配置，而项目实际使用的是独立 PHP 版本配置，得手动进对应版本的配置目录确认
最稳妥的方式：每次修改后，用 php --ri swoole | grep -E "(use_shortname|coroutine)" 直接验证输出，别信“应该改好了”。
