在 Yii2 框架中实现二级域名功能，不仅是提升网站 SEO 权重的有效手段，更是构建多租户 SaaS 系统或进行业务模块化隔离的核心技术方案，通过将 Web 服务器的通配符解析与 Yii2 的路由机制及请求处理组件深度结合，开发者可以灵活地实现基于子域名的模块分发、动态参数传递以及数据隔离，从而在提升用户体验的同时，大幅增强网站的结构化专业度。
二级域名在 Yii2 架构中的战略价值
从 SEO 和架构设计的双重角度来看，二级域名的应用具有不可替代的优势。对于搜索引擎而言，二级域名通常被视为独立的站点，这意味着通过合理的关键词布局（如 beijing.example.com），可以将核心关键词直接植入 URL 中，从而获得比普通目录结构更高的权重和更精准的搜索匹配度，在 Yii2 的 MVC 架构中，利用二级域名进行模块化分离，能够极大地降低代码的耦合度，将商城、论坛、用户中心分别拆分为 shop、bbs、user 二级域名，不仅便于团队协作开发，还能针对不同模块配置独立的组件和行为，实现真正的业务解耦。
基于 Nginx 的通配符解析配置
实现 Yii2 二级域名的第一步，是在 Web 服务器层面配置通配符解析，以生产环境常用的 Nginx 为例，需要配置 Server 块以接收所有子域名的请求，并将其统一指向 Yii2 的入口文件（通常是 index.php）。关键在于使用正则表达式捕获子域名部分，并将其作为参数传递给后端。
在 Nginx 配置文件中，可以这样设置：
server {
listen 80;
server_name ~^(?<subdomain>.+)\.example\.com$;
root /path/to/yii2/frontend/web;
location / {
index index.php;
try_files $uri $uri/ /index.php?$args;
}
location ~ \.php$ {
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# 将捕获的子域名传递给 PHP
fastcgi_param HTTP_HOST $host;
fastcgi_param SUBDOMAIN $subdomain;
}
}
此配置确保了无论是 api.example.com 还是 admin.example.com，请求都能被正确路由到 Yii2 框架进行处理，同时保留了子域名的信息。
Yii2 框架层面的动态路由与参数捕获
当 Nginx 将请求转发给 Yii2 后，框架需要识别并处理这些子域名。最专业且符合 Yii2 规范的做法是在应用的入口脚本或引导组件中进行解析，不建议在控制器中直接判断 $_SERVER['HTTP_HOST']，这会破坏 MVC 的整洁性。
推荐在 config/web.php 或 config/bootstrap.php 中通过 on beforeRequest 事件来捕获并处理子域名逻辑，可以定义一个 UrlManager 的规则，或者直接在请求对象中注入参数。
// 在 config/web.php 的 components 配置中
'request' => [
'cookieValidationKey' => 'your_key',
'parsers' => [
'application/json' => 'yii\web\JsonParser',
],
],
// 在 bootstrap 过程中解析子域名
'on beforeRequest' => function () {
$host = Yii::$app->request->hostName;
$parts = explode('.', $host);
if (count($parts) > 2) {
$subdomain = $parts[0];
// 将子域名设置为全局参数，供路由或控制器使用
Yii::$app->params['subdomain'] = $subdomain;
// 动态路由示例：如果是 api 子域名，路由到 api 模块
if ($subdomain === 'api') {
Yii::$app->set('urlManager', [
'class' => 'yii\web\UrlManager',
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => require(__DIR__ . '/routes/api.php'),
]);
}
}
},
这种方法保证了核心逻辑的封装性,使得 Yii2 能够根据不同的二级动态加载不同的路由规则或模块配置，实现了高度的灵活性。
多租户场景下的数据库动态切换方案
在构建 SaaS 系统时，二级域名往往代表不同的租户。Yii2 强大的依赖注入容器使得动态切换数据库连接变得异常简单且优雅，在识别出子域名后，可以根据子域名（即租户 ID）动态修改 db 组件的配置。
这通常通过创建一个自定义的组件或在 beforeRequest 事件中重写数据库连接来实现，每个租户拥有独立的数据库，或者共享数据库但通过不同的表前缀区分。
// 动态数据库切换逻辑示例
'on beforeRequest' => function () {
$subdomain = Yii::$app->params['subdomain'] ?? null;
if ($subdomain) {
// 假设租户数据存储在主库中，先获取租户配置
$tenantConfig = Tenant::find()->where(['slug' => $subdomain])->one();
if ($tenantConfig) {
// 动态修改 db 组件配置
Yii::$app->set('db', [
'class' => 'yii\db\Connection',
'dsn' => "mysql:host=127.0.0.1;dbname={$tenantConfig->db_name}",
'username' => $tenantConfig->db_user,
'password' => $tenantConfig->db_pass,
'charset' => 'utf8mb4',
]);
}
}
},
这种方案必须配合缓存机制使用，例如将租户配置信息缓存到 Redis 中，避免每次请求都查询主数据库，从而保证高性能。
跨域 Cookie 共享与安全防护策略
在二级域名架构中,Cookie 的共享与安全是极易被忽视的关键点，为了实现主域名与子域名之间的登录状态同步（例如在 www.example.com 登录后，user.example.com 也处于登录状态），必须配置 Cookie 的 domain 属性。
在 Yii2 的 user 组件配置中，设置 identityCookie 参数：
'user' => [
'identityClass' => 'common\models\User',
'enableAutoLogin' => true,
'identityCookie' => ['name' => '_identity', 'httpOnly' => true, 'domain' => '.example.com'],
],
'session' => [
'cookieParams' => [
'domain' => '.example.com',
'httpOnly' => true,
],
],
必须严格防范 Host Header 注入攻击，由于应用逻辑依赖于 HTTP_HOST，恶意用户可能伪造 Host 头来欺骗后端，在获取子域名后，务必进行白名单验证或正则严格校验，确保只包含合法的字母数字字符，防止应用程序将敏感信息泄露给错误的域名或执行未授权的逻辑。
相关问答
Q1：在 Yii2 中使用二级域名会对性能产生多大影响，如何优化？
A： 二级域名解析本身对性能的影响微乎其微，主要开销在于基于子域名的动态逻辑（如数据库切换），为了优化，首先应利用 Nginx 的 FastCGI 缓存缓存静态资源；在 PHP 层面，务必将子域名对应的租户配置信息（如数据库连接信息、路由规则）进行缓存（推荐使用 Redis 或 APCu），避免每次请求都进行 I/O 操作查询配置表，确保 on beforeRequest 中的逻辑尽可能轻量。
Q2：如何实现二级域名与主域名的 Session 共享？
A： 实现 Session 共享的核心在于 PHP 的 Session ID 存储方式和 Cookie 域名设置，在 Yii2 配置文件中，将 session 组件的 cookieParams 的 domain 设置为 .example.com（注意前面的点），如果服务器是多机部署，必须将 Session 存储方式从默认的文件存储改为 Redis 或 Memcached 等共享存储，确保不同服务器节点都能读取到相同的 Session 数据，配置示例如：'session' => ['class' => 'yii\redis\Session', 'redis' => 'redis', 'cookieParams' => ['domain' => '.example.com']]。
互动
如果您在实施 Yii2 二级域名配置过程中遇到了关于路由重写或 Nginx 兼容性的具体问题，欢迎在评论区分享您的困惑，我们将为您提供更具针对性的技术建议。
