Yii2 URL 规则键统一添加前缀方法

Yii2 的 GroupUrlRule 类提供了一种优雅且官方推荐的方式，通过设置 prefix 属性即可为整组 URL 规则的匹配路径（规则键）自动批量添加统一前缀（如 /api），彻底避免在每条规则中重复书写冗长路径、降低出错风险，并大幅提升路由配置的可维护性、可读性与后期扩展能力——尤其适用于大型 API 项目，它不仅支持精准匹配和路由生成（Url::to()），还契合 Yii2 的设计哲学，是替代硬编码、字符串拼接或 Web 服务器重写规则的真正标准解决方案。

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/'；
• 组内空字符串 '' 规则将精确匹配 /api（注意：不是 /api/，若需匹配后者，可写 '/' => ...）；
• GroupUrlRule 不影响右侧 route 值，_public// 仍按常规解析控制器与动作。

⚠️ 注意事项与最佳实践

• 顺序敏感：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 设计哲学的最佳实践。

好了，本文到此结束，带大家了解了《Yii2 URL 规则键统一添加前缀方法》，希望本文对你有所帮助！关注golang学习网公众号，给大家分享更多文章知识！