Yii框架Session与Cookie使用教程

本文深入剖析了Yii 2框架中Session与Cookie的安全使用规范与常见陷阱，强调必须严格遵循`response->cookies`写入、`request->cookies`读取的双向隔离原则，并指出Session需显式`open()`、受`save_path`/时区/`sameSite`等配置深度影响；特别警示Yii 1与Yii 2的`CHttpCookie`/`CHttpSession`完全不兼容，混用将导致静默失效；同时揭露易被忽视的关键安全细节——如未设`httpOnly`和`secure`带来的XSS与明文传输风险、未启用签名验证的Cookie可被篡改、默认`PHPSESSID`名和缺失`SameSite`引发的CSRF隐患，以及直接操作`$_SESSION`绕过框架保护的巨大风险，堪称Yii开发者保障认证与状态管理安全的必读避坑指南。

Yii 1 和 Yii 2 的 Session / Cookie 用法不兼容，混用会导致读不到、写失败或静默丢弃 —— 尤其是 CHttpCookie（Yii 1）和 \yii\web\Cookie（Yii 2）完全不是一回事，别抄错代码。

Yii 2 中怎么安全设置和读取 Cookie

必须区分「写入」和「读取」两个方向：写用 response->cookies，读用 request->cookies。这是硬性约定，反了就无效。

• response->cookies->add() 才真正把 cookie 发送到浏览器；response->cookies->remove() 才能清除已存在的 cookie
• request->cookies->get('name') 或 request->cookies['name']->value 才能拿到用户发来的 cookie 值
• 没设 httpOnly = true 的 cookie 可被 XSS 读取；没设 secure = true（HTTPS 环境下）的 cookie 可能被明文传输
• 如果启用了 cookie 验证（enableCookieValidation = true），所有通过 request->cookies 读取的值都自动校验签名，但你不能手动构造未签名的 cookie 写入

示例：

$cookie = new \yii\web\Cookie([
    'name' => 'auth_token',
    'value' => 'abc123',
    'expire' => time() + 86400,
    'httpOnly' => true,
    'secure' => YII_ENV_PROD, // 生产环境强制 HTTPS
]);
\Yii::$app->response->cookies->add($cookie);

// 读取时不会报错，但 get() 返回 null 表示不存在或验证失败
$token = \Yii::$app->request->cookies->get('auth_token');

Yii 2 中 Session 操作为什么有时“不生效”

Session 不是写完立刻持久化，它依赖请求结束时自动保存，且受配置影响极大。常见失效原因不是代码错，而是环境或配置问题。

• \Yii::$app->session 默认延迟初始化，首次访问 open() 才真正启动 session —— 所以在 beforeAction 或中间件里直接赋值可能被忽略
• 如果 session.save_path 不可写，或磁盘满，session_start() 失败，但 Yii 默认不抛异常，只静默禁用 session
• \Yii::$app->session->destroy() 会删服务器端数据并重置 session ID，但不会清除浏览器里的 session cookie；要彻底退出，还得配合删除登录态 cookie
• 调用 clear() 只清数据，不销毁 session 文件；close() 主动结束写入，避免后续修改被丢弃

建议始终显式检查是否活跃：

if (\Yii::$app->session->isActive === false) {
    \Yii::$app->session->open();
}
\Yii::$app->session['user_id'] = 123;

Yii 1 的 CHttpSession 和 CHttpCookie 还能用吗

不能在 Yii 2 项目里直接用。类名、方法签名、生命周期管理全变了，强行 require 或 alias 会导致 Class 'CHttpCookie' not found 或运行时行为异常。

• Yii 1 的 Yii::app()->request->cookies 是 CCookieCollection 实例，Yii 2 的 \Yii::$app->request->cookies 是 \yii\web\CookieCollection
• Yii 1 的 expire 字段是秒级时间戳，Yii 2 的 expire 同样是时间戳，但部分旧教程误写成相对秒数（如 +3600），这在 Yii 2 中会变成 1970 年的时间，导致 cookie 立刻过期
• 迁移时最易踩的坑：把 Yii 1 的 $cookie->expire = time()+86400 直接复制进 Yii 2，看起来没错，但若原项目用了自定义 session handler 或非标准时区，时间偏差会让 cookie 实际失效

Session ID 泄露和 Cookie 安全配置容易被忽略的点

默认配置下，Yii 2 的 session cookie 名是 PHPSESSID，路径是 /，且没设 SameSite —— 这些都会带来 CSRF 或会话劫持风险。

• 务必在应用配置中显式设置：'name' => 'myapp_session'（避免暴露技术栈）、'sameSite' => 'Lax'（防 CSRF）、'path' => '/'（确保子路由可读）
• 开发时 YII_DEBUG 开启状态下，session cookie 默认不设 secure，上线前必须检查 env 判断逻辑是否覆盖所有部署场景
• 不要用 $_SESSION 或 $_COOKIE 替代 Yii 封装 —— 它们绕过验证、不走组件生命周期、无法触发事件，调试时看似正常，上线后可能因配置变更突然失效

Session 和 Cookie 的边界必须清晰：敏感状态放 session（服务端可控），轻量标识或偏好放 cookie（客户端可删）。两者都依赖正确的时间同步、合理的过期策略和严格的传输保护 —— 差一个配置项，就可能让整个认证链路裸奔。

文中关于Yii框架的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Yii框架Session与Cookie使用教程》文章吧，也可关注golang学习网公众号了解相关技术文章。