Yii2部署必装扩展:mbstring、openssl、pdo及对应驱动、json、curl;缺一则启动报错或功能失效,需用php -m和phpinfo()分别验证CLI与Web环境。

PHP 部署 Yii2 时必装的扩展缺了会直接报错
Yii2 不是“跑起来就行”,它在启动阶段就依赖多个 PHP 扩展做基础能力校验。缺任何一个,index.php 都可能直接 500,连错误页面都看不到——比如 mbstring 缺失时,你会看到白屏或 Fatal error: Call to undefined function mb_strlen();openssl 缺失则 Composer 安装失败、JWT 验证崩溃、file_get_contents('https://...') 报错。
-
mbstring:处理多字节字符串(中文、emoji),缺了路由解析、表单验证、日志写入全挂 -
openssl:HTTPS 请求、密码哈希(password_hash)、JWT、Composer 更新全部失效 -
pdo+ 对应驱动(如pdo_mysql):数据库连接直接失败,yii\db\Connection::open()抛异常 -
json:配置加载、API 返回、缓存序列化全崩,json_encode()找不到 -
curl(非绝对强制但高频依赖):第三方 SDK(微信、支付宝)、HTTP 客户端(yii\httpclient\Client)无法工作
检查线上环境是否齐备:用 php -m 和 phpinfo()
别只信运维说“都装了”,得自己验证。SSH 进服务器后执行:
php -m | grep -E '^(mbstring|openssl|pdo|json|curl)$'
如果没输出,说明缺失。更稳妥的是建个 info.php 放 Web 目录下:,浏览器打开看对应模块是否显示“enabled”。注意:CLI 和 Web 使用的 php.ini 可能不同,php -m 查 CLI,phpinfo() 查 Web,两者都要核对。
常见部署漏掉的点:Docker / 容器里没重装扩展
Docker 构建镜像时,很多人用官方 php:8.1-apache 基础镜像,但默认不带 pdo_mysql 或 mbstring。必须显式安装:
立即学习“PHP免费学习笔记(深入)”;
RUN docker-php-ext-install mbstring pdo pdo_mysql json \ && pecl install openssl \ # 实际上 openssl 是编译时内置,这里只是示意逻辑 && docker-php-ext-enable mbstring pdo pdo_mysql json
特别注意:docker-php-ext-install 默认不启用扩展,必须配 docker-php-ext-enable;另外 gd、xml 虽非 Yii2 核心依赖,但如果你用了验证码、Excel 导出、SOAP 接口,也会当场报错。
扩展版本不兼容也会导致静默失败
比如 PHP 8.2+ 移除了 mysql_connect(),但某些老版 Yii1 兼容层或自定义组件若硬调用,会报 Undefined function mysql_connect();又比如 intl 扩展版本太低(NumberFormatter 构造失败,导致国际化数字/货币格式化出错,但错误不明显,只返回空字符串。建议按 Yii2 官方要求的最低扩展版本检查:mbstring ≥ 7.0、openssl ≥ 1.0.1、pdo 驱动需匹配 MySQL 版本(如 MySQL 8.0 推荐用 mysqlnd 驱动而非 libmysql)。
扩展不是装上就完事,版本和启用状态都得对得上。线上出问题时,先盯死 phpinfo() 里那几行,比翻日志快得多。











