静态路由基础

第 12 章我们提过一句：Astro 用的是文件路由（file-based routing），文件放在哪，网址就是哪。这一章把它讲透，顺便看看几种容易混淆的写法。

什么是静态路由

「静态路由」指的是：页面在构建时就确定好了，构建完成后网址是固定的一批。你写一篇文章，它就有一个固定的网址；你不改文件，网址就不变。

与之相对的是「动态路由」——一个文件能根据数据批量生出很多网址，那是第 15 章的内容。本章先只看「一个文件对应一个固定网址」的静态路由。

Astro 的静态路由完全由 src/pages/ 目录里的文件结构决定。你不需要写任何路由配置文件，加一个文件，就多一个网址；删一个文件，就少一个网址。这种「所见即所得」的路由，对初学者非常友好。

页面之间怎么跳转

前面已经说过，Astro 里链接页面就用标准 HTML 的 <a> 标签，没有框架专属的链接组件：

<!-- src/pages/index.astro -->
<p>了解更多 <a href="/about/">关于 Astro</a> 的内容。</p>

如果你的站点在 astro.config.mjs 里设置了 base: "/docs"（即整个站点挂在 /docs 路径下），那站内链接也要带上这个前缀：

<!-- 配置了 base: "/docs" 时 -->
<p>看我们的 <a href="/docs/reference/">参考文档</a> 部分！</p>

文件路径如何变成网址

核心规则一句话：src/pages/ 之后的路径和文件名，去掉扩展名，就是网址。 看几个对照例子就懂了：

src/pages/index.astro        -> 你的域名/
src/pages/about.astro        -> 你的域名/about
src/pages/about/index.astro  -> 你的域名/about
src/pages/about/me.astro     -> 你的域名/about/me
src/pages/posts/1.md         -> 你的域名/posts/1

拆开看：

• index.astro 永远对应目录本身那个网址。所以 src/pages/about/index.astro 和 src/pages/about.astro 访问的是同一个 /about。
• 子目录会体现在网址里。src/pages/about/me.astro 就对应 /about/me。
• .md 文件也照此规则变成页面，src/pages/posts/1.md 对应 /posts/1。

两种写法指向同一网址

有个细节初学者常纠结：/about 这个网址，到底用 about.astro 还是 about/index.astro？

答案是：两者都行，效果一样。区别只在于你更喜欢哪种文件组织：

• 用 src/pages/about.astro：所有页面平铺在 pages 目录下，适合页面不多时。
• 用 src/pages/about/index.astro：把和「about」相关的文件（比如它的子页面、专属组件）都收进 about/ 文件夹，结构更整齐，适合一块功能有很多文件时。

选择哪一种完全看你的整理习惯，网址访客是看不出来的。

不同文件类型都遵循同一套规则

静态路由不只认 .astro。前面章节提到的几种页面入口，在「路径变网址」这件事上规则完全一致：

• .astro 页面组件 → 直接变成网页。
• .md / .mdx 文件 → 也直接变成网页，前提是 MDX 装好了集成。
• .html 文件 → 同样变成网页。

只要文件在 src/pages/ 里，Astro 就按上面的对照规则给它分配网址。这让「写文章用 Markdown、写定制页用 Astro 组件」能在同一个站里和平共处。

用下划线排除页面

有时候，你想在 src/pages/ 目录里放一些「暂时不想要、但不想删」的文件，或者放一些测试、工具、组件，跟页面放一起方便管理。这些文件如果不处理，会被 Astro 当成页面构建出去，凭空多出奇怪的网址。

Astro 给了一个简单开关：文件名或目录名以 _（下划线）开头，就不会被当成路由，也不会进构建产物。

src/pages/
├── _hidden-directory/
│   ├── page1.md
│   └── page2.md
├── _hidden-page.astro
├── index.astro
└── projects/
    ├── _SomeComponent.astro
    ├── _utils.js
    └── project1.md

在上面的结构里，真正会被构建成网页、生成 HTML 文件的，只有 src/pages/index.astro 和 src/pages/projects/project1.md。其余带下划线的，都被 Astro 忽略掉了。

网址结尾的斜杠

初学时常困惑：访问 /about 和 /about/ 是一回事吗？在 Astro 里，网址结尾带不带斜杠，由项目配置里的 trailingSlash 决定（默认是 ignore，即两种写法都能访问）。

// astro.config.mjs
import { defineConfig } from "astro/config";

export default defineConfig({
  // 'ignore'（默认）两种都行；'always' 强制带斜杠；'never' 强制不带
  trailingSlash: "ignore",
});

新手不用急着改它，默认的 ignore 最省心。知道有这个开关，以后遇到「带斜杠能开、不带斜杠 404」的怪事，就知道去哪调。

构建后网址长啥样

静态路由构建完成后，所有页面会变成真实的 HTML 文件，放进 dist/ 目录。目录结构跟你 src/pages/ 基本一一对应：

src/pages/about.astro   ->  dist/about.html
src/pages/index.astro   ->  dist/index.html
src/pages/posts/1.md    ->  dist/posts/1.html

你部署时，就是把 dist/ 整个传上去。访客访问的网址，正是这些文件的路径（去掉 .html）。这也解释了为什么文件路由「所见即所得」——你在 pages 里怎么摆，构建出来就怎么摆。

两个文件指向同一网址会冲突

前面说过 about.astro 和 about/index.astro 效果一样。但千万别同时建这两个文件——它们指向同一个 /about，Astro 构建时会报「路由冲突」，直接报错停下，页面出不来。

src/pages/
├── about.astro        ← 和下面抢同一个 /about
└── about/
    └── index.astro    ← 冲突！

同样道理，别让 [slug].astro 这种动态文件和某个写死的 hello.astro 抢同一个网址。写文件时心里有个谱：一个网址最好只由一个文件负责。真要「一个网址多种内容」（比如中英文同内容），用第 16 章讲的重写（Astro.rewrite），而不是建两个文件硬碰。

静态路由够用吗

对绝大多数内容型网站——博客、文档、产品介绍页——静态路由已经足够。它的好处是：页面在构建时就生成好，部署到任何静态托管（如 GitHub Pages、Netlify、Cloudflare Pages）都能跑，速度快、成本低、还安全。

只有当你的网址数量没法提前确定（比如用户能创建任意用户名的主页），才需要用动态路由或按需渲染。那是后面章节的内容，本章先把这个最常用、最基础的静态路由吃透。

本章小结

静态路由的本质就是文件路由：src/pages/ 之后的路径决定网址，index 代表目录首页，.astro、.md、.mdx、.html 都遵循同一套规则。想临时停用或收纳非页面文件，给名字加个下划线 _ 即可。

下一章进入动态路由：一个文件如何批量生成很多个网址，以及 getStaticPaths 这个关键函数怎么用。