groupurlrule是yii2中用于分组url规则的配置结构，非独立类，不可实例化或在rules中声明class；它需作为数组项直接置于urlmanager->rules中，通过prefix和routeprefix分别控制请求路径前缀与内部路由前缀，二者混淆将导致404或invalid route错误；不支持嵌套，多级前缀须用多个并列groupurlrule实现；仅在enableprettyurl=true且web服务器重写配置正确时生效。
Yii2 的 GroupUrlRule 本质是语法糖，不是独立路由类，它只是把多个 UrlRule 打包进一个配置数组，由 UrlManager 自动展开 —— 直接写错位置或当成类名用，路由就完全不生效。
GroupUrlRule 不是类，是配置结构
你不会 new GroupUrlRule()，也不会在 rules 数组里写 'class' => 'yii\web\GroupUrlRule'。它只是 UrlManager::rules 中的一个数组项，带 'class' => 'yii\web\GroupUrlRule' 是常见误解，实际会报错：Invalid Configuration – yii\base\InvalidConfigException。
正确写法是把它当作一个「规则组配置块」，放在 urlManager->rules 里，和其他普通 UrlRule 并列：
'urlManager' => [
'rules' => [
// 普通规则
'login' => 'site/login',
// GroupUrlRule 配置块（注意：没 class 键！）
[
'prefix' => 'api',
'routePrefix' => 'api',
'rules' => [
'' => 'v1/default/index',
'v1/<controller:>/<action:>' => 'v1/<controller>/<action>',
],
],
],
],</action></controller></action:></controller:>
-
prefix控制 URL 路径前缀（如访问/api/v1/user/list） -
routePrefix控制内部路由映射前缀（如实际分发到api/v1/user/list） -
rules里的子规则，路径和路由都自动继承前缀，但写的时候**不能重复加前缀**（比如不要写'api/v1/xxx'）
prefix 和 routePrefix 容易搞反
典型现象：URL 能访问，但控制器找不到，报 Invalid Route – yii\base\InvalidRouteException；或者 URL 404 但日志里显示匹配到了错误的 route。
原因在于混淆了「用户请求的路径」和「内部路由地址」：
-
prefix只影响 URL 解析：用户必须访问/api/xxx，这个api才会被剥离，剩下的部分交给子规则匹配 -
routePrefix只影响路由拼接：子规则中写的'user/list'，最终会变成api/user/list去找控制器 - 如果
routePrefix漏写，子规则中的'user/list'就会尝试匹配user/list控制器，而不是api/user/list
嵌套 GroupUrlRule 不被支持
Yii2 官方文档没说，但实测：在 GroupUrlRule 的子 rules 里再写一个 GroupUrlRule 数组，UrlManager 不会递归处理 —— 它只展开第一层 GroupUrlRule，内层会被当普通数组忽略，导致子规则全部失效。
替代方案只有扁平化：
[
'prefix' => 'admin',
'routePrefix' => 'admin',
'rules' => [
'dashboard' => 'dashboard/index',
'users/<action:>' => 'users/<action>',
// ❌ 不要在这里再套一个 GroupUrlRule 数组
// ✅ 如果要再分组，得提一层，和当前同级写
],
],</action></action:>
- 需要多级前缀（如
/admin/v1/...），就写两个并列的GroupUrlRule，第一个prefix => 'admin'，第二个prefix => 'admin/v1' - 注意第二个的
prefix必须完整包含路径，不能只写'v1'
调试时别忘了开启 enablePrettyUrl
GroupUrlRule 只在 enablePrettyUrl => true 时起作用。如果关着，所有规则（包括 group）都不参与解析，URL 会退化成 index.php?r=xxx 格式，此时 prefix 完全无意义。
检查点：
-
urlManager->enablePrettyUrl必须为true - Web 服务器重写配置必须到位（Apache 的
.htaccess或 Nginx 的try_files） - 开发时可临时加
'showScriptName' => true排查是否真走到了路由层
最常被忽略的是：本地开发用 php -S 启动时，enablePrettyUrl 默认无效，必须配合路由器脚本（如 router.php）才能模拟重写行为。
