如何配置Yii框架以支持HTTPS和SSL证书部署？

本文共计1065个文字，预计阅读时间需要5分钟。

《Yii框架本身不处理HTTPS协议切换，真正的HTTPS配置发生在Web服务器层（Nginx/Apache/IIS）上，Yii只需适配已加密的请求环境——即在Web服务器上配置好SSL并强制跳转，再让Yii正确识别协议即可，否则会出现内容混合、重定向循环等问题，如urlManager生成HTTP链接等。》

Web 服务器必须先完成 SSL 终止和 301 跳转

这是整个流程的前提。Yii 不会帮你监听 443 端口或加载证书，这些必须由 Nginx 或 Apache 完成。

• Nginx 示例中必须包含 listen 443 ssl、ssl_certificate 和 ssl_certificate_key 三项，缺一不可；若只配了 443 但没开 ssl on（旧版）或没写 ssl（新版），请求会直接失败
• HTTP → HTTPS 强制跳转不能依赖 Yii 的 PHP 逻辑（如中间件里 header("Location: https://...")），否则可能被缓存、绕过，或在 AJAX 请求中静默失败；应使用 Web 服务器原生重写：RewriteCond %{HTTPS} off + RewriteRule（Apache）或 return 301 https://$host$request_uri（Nginx）
• IIS 用户注意：导入 PFX 证书时必须勾选“允许导出私钥”，否则后续绑定会报错 0x8009030e；且需在“SSL 设置”中勾选“要求 SSL”，否则仍可走 HTTP

Yii 必须正确识别当前是 HTTPS 请求

很多问题根源在于 Yii 认为请求仍是 HTTP，导致 Url::to()、yii\helpers\Url::home() 生成的链接带 http://，引发混合内容警告或表单提交到错误协议。

• 检查 $_SERVER['HTTPS'] 是否为 on（Apache）或 $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https'（Nginx 反向代理常见）；若 Web 服务器做了 SSL 终止但没透传协议头，Yii 就永远不知道自己跑在 HTTPS 下
• 在 web/index.php 开头手动补全（临时方案）：if (isset($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] === 'https') { $_SERVER['HTTPS'] = 'on'; }
• 更稳妥的是在应用配置中显式设置：'components' => ['request' => ['enableCsrfValidation' => true, 'csrfParam' => '_csrf-frontend', 'secure' => true, 'cookieParams' => ['httpOnly' => true, 'secure' => true]]]，其中 'secure' => true 强制 Cookie 仅通过 HTTPS 传输，也会影响部分 URL 判断逻辑

URLManager 和 baseUrl 必须匹配实际访问协议

即使请求是 HTTPS，若 urlManager 的 baseUrl 写死为 http://example.com，所有 Url::to() 生成的绝对路径都会出错。

• 不要在配置里硬编码 'baseUrl' => 'http://example.com'；改用动态方式：'baseUrl' => (isset($_SERVER['HTTPS']) && $_SERVER['HTTPS'] === 'on' ? 'https://' : 'http://') . $_SERVER['HTTP_HOST']
• 如果用了 CDN 或反向代理，$_SERVER['HTTP_HOST'] 可能是内网地址（如 localhost），此时应优先读 $_SERVER['HTTP_X_FORWARDED_HOST'] 或明确设为公网域名
• 调试技巧：在任意控制器里打印 Yii::$app->request->getAbsoluteUrl() 和 Yii::$app->urlManager->createAbsoluteUrl(['site/index'])，对比二者协议是否一致

数据库和模板中的 HTTP 链接要批量清理

Web 服务器和 Yii 配置都正确后，页面仍可能报“Mixed Content”，大概率是历史数据或模板里写死了 http://。

• 文章正文、富文本字段、图片 src、JS/CSS 外链等，需执行 SQL 替换（务必先备份）：UPDATE `article` SET `content` = REPLACE(`content`, 'http://example.com/', 'https://example.com/');
• 模板中硬编码的链接（如页脚版权、CDN 地址）必须手动改为协议相对路径（//example.com/js/app.js）或使用 Yii::$app->request->getBaseUrl() 动态生成
• 第三方组件（如 CKEditor、TinyMCE）上传的图片路径也可能含 HTTP，需检查其配置项是否支持自动转 HTTPS，或修改其返回 URL 的钩子函数

最易被忽略的是反向代理场景下 $_SERVER 变量未被正确覆盖 —— Nginx 传了 X-Forwarded-Proto，但 PHP-FPM 默认不信任该头，需要在 fastcgi_param 中显式转发，否则 Yii 永远收不到 HTTPS 标识。