Vista.js 路由完全指南文件路由、动态参数与嵌套布局一次讲透【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vistaVista.js 是一个 React 19 全栈框架它的核心是文件路由你在app/目录下创建什么文件浏览器里就能访问什么地址。本文用最少的代码把 Vista.js 路由的三块基石——文件路由约定、动态参数含通配符、嵌套布局——一次讲透帮你从看文件猜 URL到看 URL 定位文件。一、为什么 Vista.js 路由值得花 10 分钟搞懂传统框架里路由是注册出来的新建页面要在路由表里加一行。而 Vista.js 走的是 Next.js App Router 同样的心智模型——文件即路由。这带来三个直接好处️零配置新增页面 新增一个文件刷新即生效可逆推导看到/docs/ai/rag这个地址立刻能在磁盘上找到对应文件自动嵌套文件夹层级天然生成布局包裹关系共享导航栏不用手写官方的一句话定义是Folders underapp/are routes.细节都在 packages/vista/docs/app.md。二、文件路由一张表看懂目录与 URL 的对应关系这是 Vista.js 文件路由约定与 Next.js 最关键的两处差异新手最容易踩坑文件路径对应 URL说明app/index.tsx/首页。没有app/page.tsx约定app/root.tsx—根布局。没有app/layout.tsx约定app/about/page.tsx/about静态路由一层文件夹一段路径app/blog/[slug]/page.tsx/blog/my-post动态段方括号占位app/docs/[...slug]/page.tsx/docs/ai/rag通配段吃掉剩余所有层级app/api/users/route.ts/api/usersHTTP 接口导出GET/POST等函数 记忆口诀首页看index.tsx布局看root.tsx页面看page.tsx接口看route.ts。一个真实项目的目录长这样来自 README.mdmy-app/ ├── app/ │ ├── root.tsx # 根布局html、字体、共享外壳 │ ├── index.tsx # 首页 → / │ ├── about/page.tsx # → /about │ └── globals.css └── vista.config.ts想直接对照真实代码仓库里的示例应用 sample-app/app/index.tsx 和 sample-app/app/root.tsx 就是最简的首页 根布局组合。三、动态参数如何让一个文件服务一万个 URL动态段[slug]方括号文件夹是参数槽。app/blog/[slug]/page.tsx会同时响应/blog/ship-log、blog/launch-day等所有单级路径。这个模式常用于博客、商品详情、工单列表——一个模板文件服务无限内容页。通配段[...slug]省略号前缀表示捕获剩余全部层级app/docs/[...slug]/page.tsx → /docs/introduction/the-beginning-of-vista通配路由对文档站尤其有用分类 文章的完整路径都来自内容数据目录不用跟着内容层级无限膨胀。参数形状的统一处理不同运行时适配器可能把通配参数以string或string[]两种形状传入。官方推荐的写法是一个归一化工具函数无论拿到字符串还是数组都拆成string[]再处理。完整模式见 dynamic-routes-and-slugs.md官方文档站的解析器就落在 apps/web/app/docs/ 下的[...slug]页面文件里。 长尾经验不要在页面里new URL(location.pathname)手动解析路径段直接读路由参数对象最稳。四、嵌套布局文件夹层级自动变成嵌套外壳布局是 Vista.js 路由里免费获得的能力某个文件夹里的layout.tsx会包裹该文件夹下所有页面。以官方文档站为例子结构来自 project-file-structure.mdapp/root.tsx → 全局外壳主题、字体、Navbar/Footer app/docs/layout.tsx → 文档外壳侧边栏 目录 TOC app/docs/page.tsx → 文档首页 /docs app/docs/[...slug]/page.tsx → 任意文章页 /docs/分类/slug访问/docs/core-concepts/routing-overview时渲染顺序是root.tsx包裹一切docs/layout.tsx提供侧边栏和目录[...slug]/page.tsx渲染具体文章正文你不需要写任何路由嵌套代码——目录结构就是组件树。修改docs/layout.tsx一处全站所有文档页同步更新。真实实现可对照 apps/web/app/docs/layout.tsx 和 apps/web/app/docs/doc-navigation.tsx。五、页面里的客户端边界use client放哪文件路由的页面默认是 Server Component服务端直接输出 HTML浏览器 JS 更少。只有需要useState、事件监听、动画效果的模块才在文件顶部加一行use client。规则速查✅app/、components/、utils/、lib/、src/五个目录都允许出现客户端模块✅ 把交互组件从page.tsx拆进components/page.tsx保持服务端❌ 不要整页都标use client会失去服务端渲染的性能优势六、新手落地清单5 步写对你的第一条路由npx create-vista-applatest my-app脚手架新项目详见 create-and-generate.md改 sample-app 式 的app/index.tsx验证首页生效新建app/about/page.tsx刷新访问/about——静态路由完成 ✅需要参数加app/blog/[slug]/page.tsx需要深层路径升级为[...slug]要给一组页面加共享外壳在对应文件夹放layout.tsx根级除外根外壳是root.tsx开发服务器默认端口3003生产构建输出在.vista/不要提交到仓库。七、延伸阅读官方资料相对路径资料路径App 约定路由/客户端/配置packages/vista/docs/app.md路由总览apps/web/content/docs/core-concepts/routing-overview.md动态段与 slug 归一化apps/web/content/docs/core-concepts/dynamic-routes-and-slugs.md项目目录职责划分apps/web/content/docs/getting-started/project-structure.md完整文件结构参考apps/web/content/docs/reference/project-file-structure.md最小示例应用sample-app/一句话总结Vista.js 路由 文件即路由 [slug]动态段 文件夹即布局。掌握这三点99% 的 URL 设计问题你都能靠建一个文件解决。【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考