本文介绍 Yii2 中使用 GroupUrlRule 为所有路由规则键（即 URL 匹配模式）自动添加公共前缀（如 /api），避免重复书写、提升可维护性，无需依赖 .htaccess 或手动拼接。
本文介绍 yii2 中使用 `groupurlrule` 为所有路由规则键（即 url 匹配模式）自动添加公共前缀（如 `/api`），避免重复书写、提升可维护性，无需依赖 `.htaccess` 或手动拼接。
在 Yii2 应用开发中，当需要将大量路由统一归入某个命名空间（例如 RESTful API 接口统一以 /api 开头），若逐条在 urlManager 的 rules 数组中手动添加 'api/...' => '...'，不仅冗余易错，更难以维护——尤其当规则达数百条时，修改前缀成本极高。
此时，yii\web\GroupUrlRule 是官方推荐且最优雅的解决方案。它专为“分组路由”设计，其 $prefix 属性作用于所有子规则的匹配路径（即规则键），而非路由目标（即规则值），完美契合你的需求。
✅ 正确用法：使用 GroupUrlRule 批量注入前缀
在 config/web.php（或对应配置文件）的 urlManager 组件中，将需加前缀的规则包裹进 GroupUrlRule 实例：
'urlManager' => [
'enablePrettyUrl' => true,
'showScriptName' => false,
'rules' => [
// 其他不带前缀的规则（如前台页面）
'' => 'site/index',
'<controller>/<action>' => '<controller>/<action>',
// ? 使用 GroupUrlRule 统一添加 '/api' 前缀
new \yii\web\GroupUrlRule([
'prefix' => 'api', // ← 关键：自动为每个子规则键添加此前缀
'rules' => [
'' => '_public/site/index', // 匹配 /api → 解析为 _public/site/index
'<controller>/<action>' => '_public/<controller>/<action>',
'<controller>' => '_public/<controller>/index',
// 可继续添加数十甚至数百条规则，均自动生效 /api/xxx
],
]),
// 其他独立规则...
],
],? 效果说明：上述配置中，'' => '_public/site/index' 在组内实际等价于 'api' => '_public/site/index'；'<controller>/<action>' 则等价于 'api/<controller>/<action>' —— 前缀由框架自动注入，开发者只需关注逻辑路径。
⚠️ 注意事项与最佳实践
根路径映射：若需支持 /api（无后续路径）直接映射到某个动作，请在 GroupUrlRule 的 rules 中显式定义空字符串规则 ''（如上例），不要写 '/' —— Yii2 路由解析中 '/' 表示绝对路径，而空字符串 '' 才表示“当前组前缀下的根”。
规则顺序很重要：GroupUrlRule 本身是一条规则，与其他规则同级参与匹配。建议将其置于通用规则之后、特定高优规则之前，避免被更宽泛的通配规则（如 '<controller>/<action>'）提前捕获。
不推荐用 .htaccess 替代：虽然 Apache 的 RewriteRule 可做 URL 重写，但它仅修改请求路径，无法改变 Yii2 内部路由匹配逻辑，也无法让 Url::to() 等辅助方法自动生成带前缀的 URL，违背框架设计原则，且丧失跨环境兼容性（Nginx、CLI 等场景失效）。
嵌套与复用：GroupUrlRule 支持多层嵌套（如 api/v1/...），也可结合 $routePrefix（作用于规则值）实现更复杂的路由组织，但本例中仅需 $prefix 即可满足核心诉求。
✅ 总结
通过 GroupUrlRule + $prefix，你彻底告别了复制粘贴 /api/ 的机械劳动。它轻量、原生、可读性强，是 Yii2 处理大规模分组路由的标准范式。无论项目规模如何增长，只需维护清晰的分组结构，即可确保 URL 设计一致性与长期可维护性。
