Yii2 提供 GroupUrlRule 类，可通过其 prefix 属性自动为一组 URL 规则的匹配路径（即规则键）批量添加公共前缀，避免重复书写如 'api/...'，大幅提升路由配置的可维护性与可读性。
yii2 提供 `groupurlrule` 类，可通过其 `prefix` 属性自动为一组 url 规则的**匹配路径（即规则键）**批量添加公共前缀，避免重复书写如 `'api/...'`，大幅提升路由配置的可维护性与可读性。
在 Yii2 应用中，当需要为大量 API 路由统一添加 /api 前缀（例如将 'user/list' => 'api/user/list' 映射为 /api/user/list），若手动在每条规则的 key 中重复写 'api/...'，不仅冗余易错，更难以后期统一调整（如升级为 /v1/api）。此时，yii\web\GroupUrlRule 是官方推荐且最优雅的解决方案——它专为“对规则键批量加前缀”而设计。
✅ 正确用法：使用 GroupUrlRule 统一管理带前缀的规则组
只需将具有相同路径前缀的规则封装进 GroupUrlRule 实例，并设置 prefix 属性即可。该前缀会自动拼接到组内每条规则的 key（左侧路径）之前，而不会影响右侧的路由值（route）：
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => [
// 其他不带前缀的规则（如首页、后台等）
'' => 'site/index',
'<controller:\w+>/<action:\w+>' => '<controller>/<action>',
// ? 使用 GroupUrlRule 为 API 路由统一添加 '/api' 前缀
new \yii\web\GroupUrlRule([
'prefix' => 'api',
'rules' => [
'' => '_public/site/index', // 匹配 /api
'<controller:\w+>' => '_public/<controller>/index',
'<controller:\w+>/<action:\w+>' => '_public/<controller>/<action>',
// 可继续添加数十甚至数百条规则，全部自动拥有 /api/ 前缀
],
]),
// 其他规则（如管理后台）
'admin/<controller>/<action>' => 'admin/<controller>/<action>',
],
],? 关键说明：
- prefix => 'api' 作用于规则 key，因此 '<'controller:\w+>' 在组内实际等效于 'api/<controller:\w+>'；
- 组内空字符串 '' 规则将精确匹配 /api（注意：不是 /api/，若需匹配后者，可写 '/' => ...）；
- GroupUrlRule 不影响右侧 route 值，_public/<controller>/<action> 仍按常规解析控制器与动作。
⚠️ 注意事项与最佳实践
- 顺序敏感：GroupUrlRule 与其他规则一样参与匹配，建议将通用前缀组（如 API）放在靠后位置，避免覆盖更具体的静态规则（如 'api/login' => 'auth/login' 应显式声明在 group 外，或确保其正则足够精确）；
- 不支持嵌套 Group：GroupUrlRule 的 rules 数组中不能再嵌套另一个 GroupUrlRule（Yii2 当前版本限制）；
- 勿混淆 $prefixRoute：$prefixRoute 是为右侧路由值（route） 添加前缀（如自动补全模块名），与本需求无关；
- .htaccess 不适用此场景：重写规则（如 Apache 的 RewriteRule）只能修改请求路径并转发，无法动态改变 Yii 的路由解析逻辑；它不能替代 GroupUrlRule 对规则定义层面的抽象，且丧失路由生成（Url::to()）能力。
✅ 总结
GroupUrlRule 是 Yii2 官方提供的、专用于解决“URL 规则键批量加前缀”问题的标准方案。相比硬编码、字符串拼接或外部重写，它具备类型安全、可调试、支持路由生成、易于维护等核心优势。对于包含数百条 API 路由的项目，采用该方式可显著降低配置复杂度，是符合 Yii2 设计哲学的最佳实践。
