> ## Documentation Index
> Fetch the complete documentation index at: https://bun.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 文件系统路由器

> Bun 提供了一个快速的 API 用于根据文件系统路径解析路由

该 API 主要面向库作者。目前仅支持 Next.js 风格的文件系统路由，但未来可能会添加其他风格。

## Next.js 风格

`FileSystemRouter` 类可以针对 `pages` 目录解析路由。（Next.js 13 的 `app` 目录暂不支持。）考虑如下的 `pages` 目录结构：

```txt theme={"theme":{"light":"github-light","dark":"dracula"}}
pages
├── index.tsx
├── settings.tsx
├── blog
│   ├── [slug].tsx
│   └── index.tsx
└── [[...catchall]].tsx
```

`FileSystemRouter` 可用于针对该目录解析路由：

```ts router.ts theme={"theme":{"light":"github-light","dark":"dracula"}}
const router = new Bun.FileSystemRouter({
  style: "nextjs",
  dir: "./pages",
  origin: "https://mydomain.com",
  assetPrefix: "_next/static/"
});

router.match("/");

// =>
{
  filePath: "/path/to/pages/index.tsx",
  kind: "exact",
  name: "/",
  pathname: "/",
  src: "https://mydomain.com/_next/static/pages/index.tsx"
}
```

查询参数会被解析并通过 `query` 属性返回。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
router.match("/settings?foo=bar");

// =>
{
  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/settings.tsx",
  kind: "dynamic",
  name: "/settings",
  pathname: "/settings?foo=bar",
  src: "https://mydomain.com/_next/static/pages/settings.tsx",
  query: {
    foo: "bar"
  }
}
```

路由器会自动解析 URL 参数，并通过 `params` 属性返回：

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
router.match("/blog/my-cool-post");

// =>
{
  filePath: "/Users/colinmcd94/Documents/bun/fun/pages/blog/[slug].tsx",
  kind: "dynamic",
  name: "/blog/[slug]",
  pathname: "/blog/my-cool-post",
  src: "https://mydomain.com/_next/static/pages/blog/[slug].tsx",
  params: {
    slug: "my-cool-post"
  }
}
```

`.match()` 方法也接受 `Request` 和 `Response` 对象，会使用它们的 `url` 属性来解析路由。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
router.match(new Request("https://example.com/blog/my-cool-post"));
```

路由器会在初始化时读取目录内容。要重新扫描文件，使用 `.reload()` 方法。

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
router.reload();
```

## 参考

```ts theme={"theme":{"light":"github-light","dark":"dracula"}}
interface Bun {
  class FileSystemRouter {
    constructor(params: {
      dir: string;
      style: "nextjs";
      origin?: string;
      assetPrefix?: string;
      fileExtensions?: string[];
    });

    reload(): void;

    match(path: string | Request | Response): {
      filePath: string;
      kind: "exact" | "catch-all" | "optional-catch-all" | "dynamic";
      name: string;
      pathname: string;
      src: string;
      params?: Record<string, string>;
      query?: Record<string, string>;
    } | null
  }
}
```