[!info] related notes

• 所属 MOC:
• 前置概念: nextjs-file-system-routing、routing
• 并列概念:
• 易混淆概念:
• 关系笔记:

Next.js Route Groups

一句话定义

Next.js Route Group 使用括号目录：

(auth)
(app)
(marketing)

对路由代码进行逻辑分组，但括号中的组名不会成为 URL segment。

为什么需要 Route Group

假设产品有：

/login
/register
/goals
/settings

从代码组织上，你希望区分：

认证区域
应用内部区域

但不希望 URL 变成：

/auth/login
/app/goals

就可以写：

app/
├── (auth)/
│   ├── login/
│   │   └── page.tsx
│   └── register/
│       └── page.tsx
│
└── (app)/
    ├── goals/
    │   └── page.tsx
    └── settings/
        └── page.tsx

最终 URL 仍然是：

/login
/register
/goals
/settings

Route Group 与普通文件夹的区别

app/auth/login/page.tsx
→ /auth/login

而：

app/(auth)/login/page.tsx
→ /login

所以括号是一个明确语义：

组织路由树，但不要修改公开 URL。

典型用途

按产品区域组织

(marketing)
(auth)
(app)
(admin)

为不同区域建立不同 Layout Boundary

Route Group 经常和 layout.tsx 一起使用，让认证区、营销区、Dashboard 区拥有不同布局，而 URL 保持简洁。

例如：

app/
├── (marketing)/
│   ├── layout.tsx
│   └── pricing/page.tsx
└── (app)/
    ├── layout.tsx
    └── dashboard/page.tsx

这部分布局嵌套机制继续看下一节的 layout.tsx。

Route Group 不是权限控制

把：

(goals)
(admin)

写进目录，不会自动产生：

• 登录校验
• Role / Permission
• Authorization

它只是代码和路由树的组织机制。

Route Group
≠ Auth Guard
≠ Authorization Boundary

权限仍然必须由实际认证与授权逻辑实现。

Route Group 也不是 URL Namespace

如果业务真的需要公开 URL：

/admin/users

那就应该有真正的普通 segment：

app/admin/users/page.tsx

而不是把 (admin) 当成 URL 层级。

设计原则

Route Group 应表达稳定的产品/布局组织边界，而不是为了“目录看起来整齐”随意加括号。

好的分组往往可以回答：

这批页面是否共享相似布局？
是否属于同一产品区域？
是否需要和另一批 Route 在代码树上明显隔离？

如果答案都是否，就不一定需要 Route Group。

最短记忆方式

folder     → 进入 URL
(group)    → 不进入 URL，只组织路由树

普通 segment 与 page.tsx 规则见 Next.js 文件系统路由。