企业官网建设流程全解析

Vista.js 路由完全指南：文件路由、动态参数与嵌套布局一次讲透

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista

Vista.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 最关键的两处差异，新手最容易踩坑：

💡 记忆口诀：首页看index.tsx，布局看root.tsx，页面看page.tsx，接口看route.ts。

一个真实项目的目录长这样（来自 README.md）：

my-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.md）：

app/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时，渲染顺序是：

1. root.tsx包裹一切
2. docs/layout.tsx提供侧边栏和目录
3. [...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 步写对你的第一条路由

1. npx create-vista-app@latest my-app脚手架新项目（详见 create-and-generate.md）
2. 改 sample-app 式 的app/index.tsx验证首页生效
3. 新建app/about/page.tsx，刷新访问/about——静态路由完成 ✅
4. 需要参数？加app/blog/[slug]/page.tsx；需要深层路径？升级为[...slug]
5. 要给一组页面加共享外壳？在对应文件夹放layout.tsx（根级除外，根外壳是root.tsx）

开发服务器默认端口3003，生产构建输出在.vista/（不要提交到仓库）。

七、延伸阅读：官方资料相对路径

一句话总结：Vista.js 路由 = 文件即路由 +[slug]动态段 + 文件夹即布局。掌握这三点，99% 的 URL 设计问题你都能靠"建一个文件"解决。

【免费下载链接】vista项目地址: https://gitcode.com/gh_mirrors/vista13/vista