# Fumadocs (Framework Mode, Next.js): 快速入門
URL: /zh-TW/docs/next
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/index.zh-TW.mdx

開始使用 Fumadocs

# Set up Fumadocs

Instructions for AI agents to set up Fumadocs on Next.js. The setup changes between versions, so run the commands below and read the linked docs instead of writing the setup from memory. Add `.md` to the URL of a docs page to read it as Markdown.

## New Site

Create a new docs site in a new folder, or as a workspace package of a monorepo:

```bash
npx create-fumadocs-app@latest my-docs --template +next+fuma-docs-mdx --install --yes
```

For a static site, use the `+next+fuma-docs-mdx+static` template.

- `my-docs` is the folder to create.
- `--yes` skips the prompts, and the options you don't pass use their defaults. The options are listed in https://fumadocs.dev/docs/cli/create-fumadocs-app.md

## Existing App

To add docs to an existing app, run the CLI in the folder of the app:

```bash
npx @fumadocs/cli@latest init
```

- The CLI detects the framework, and adds the docs pages with their own layout beside the existing routes.
- `--i18n` sets up internationalization.
- The CLI asks before it overwrites a file. Without a terminal, it keeps the file and prints its name. Pass `--yes` only when every file it writes can be overwritten.

To set up by hand, or to merge a file that the CLI kept, follow https://fumadocs.dev/docs/next/manual-installation.md

## After the Setup

Both commands print the next steps. Start the dev server and open the docs, at `/docs` unless the output names another path.

For the tasks that follow, read the docs page of the task first:

- Writing pages: https://fumadocs.dev/docs/next/markdown.md
- Organizing pages and folders: https://fumadocs.dev/docs/next/page-conventions.md
- Customizing the UI: https://fumadocs.dev/docs/next/guides/customize-ui.md
- Changing the theme and colors: https://fumadocs.dev/docs/ui/theme.md
- Other tasks: https://fumadocs.dev/llms.txt lists every docs page.

## 術語 [#terminology]

**Markdown/MDX：** Markdown 是一種用來撰寫格式化文字的標記語言。Fumadocs 原生支援 Markdown 與 MDX (Markdown 的超集) 。

**[Bun](https://bun.sh)：** 一種 JavaScript 執行階段，本指南會使用它來執行指令碼。如果您偏好 Node.js，可以改用 [unrun](https://gugustinette.github.io/unrun/guide/getting-started.html#cli)。

若想進一步自訂，具備一些 React.js 基礎知識會很有幫助。

## 自動安裝 [#automatic-installation]

需要 Node.js 22 或以上版本。

```npm
npm create fumadocs-app
```

系統會詢問您要使用哪一個內建範本：

* **框架**：Next.js、React Router、TanStack Start、Waku 和 Astro。
* **內容來源**：Fumadocs MDX 或 Astro 內容集合。

接著會初始化一個新的 Fumadocs 應用程式，並預設設定好以下功能：

* [LLM 整合](/docs/next/integrations/llms)。
* [動態中繼資料圖片](/docs/next/integrations/og)。

<Callout title="要從現有的程式碼庫開始？">
您可以參考[手動安裝](/docs/next/manual-installation)指南來開始使用。
</Callout>

### 開始享受吧！ [#enjoy]

請在 docs 資料夾中建立您的第一個 MDX 檔案。

```mdx title="content/docs/index.mdx"
---
title: Hello World
---

## Yo what's up
```

以開發模式執行應用程式：

```npm
npm run dev
```

開啟 http://localhost:3000/docs 即可查看您的頁面。

## 常見問題 [#faq]

以下整理了您可能會遇到的一些常見問題。

<Accordions>
<Accordion id="upgrade-fumadocs" title="遇到 API 缺失或程式錯誤的問題？">
該 API 或修正可能只在較新的版本中提供。請[升級 Fumadocs](/docs/next/upgrade) 後再試一次。
</Accordion>

<Accordion id="change-base-url" title="如何變更文件的基底路由？">
路由由 Next.js 處理。請先移動文件路由 (`/docs/*` -&gt; `/info/*`) 。

重新命名路由：

<Files>
<Folder name="app/docs" defaultOpen disabled>
<File name="layout.tsx" />
</Folder>

<Folder name="app/info" defaultOpen>
<File name="layout.tsx" />
</Folder>
</Files>

或使用路由群組，將 `/docs/*` 改為 `/*`：

<Files>
<Folder name="app/(docs)" defaultOpen>
<File name="layout.tsx" />
</Folder>
</Files>

最後，請在 `source.ts` 中更新頁面的基礎 URL：

```ts title="lib/source.ts"
import { loader } from 'fumadocs-core/source';

export const source = loader({
  baseUrl: '/info', // 改成新的路徑 [!code highlight]
});
```

範本在 `lib/shared.ts` 中將此值定義為 `docsRoute`，請在該處修改，Markdown 連結便會隨之更新。
</Accordion>

<Accordion id="multi-docs" title="如何實作多份文件？">
建議使用[版面配置頁籤](/docs/ui/layouts/docs#layout-tabs)。
</Accordion>

<Accordion id="custom-layout-docs-page" title="如何在 /docs 中建立不使用文件版面配置的頁面？">
做法與在 Next.js App Router 中管理版面配置相同：請先從內容目錄 (`/content/docs`) 中移除原本的 MDX 檔案，
以免重複的頁面造成錯誤。

接著，您可以將該頁面放到另一個路由群組中，且該群組不能位於文件版面配置之下。

例如，若要取代 `/docs/test`：

<Files>
<File name="(home)/docs/test/page.tsx" />

<Folder name="docs" defaultOpen>
<File name="layout.tsx" />

<File name="[[...slug]]/page.tsx" />
</Folder>
</Files>

若是 `/docs`，您需要將 catch-all 路由改為非選用：

<Files>
<File name="(home)/docs/page.tsx" />

<Folder name="docs" defaultOpen>
<File name="layout.tsx" />

<File name="[...slug]/page.tsx" />
</Folder>
</Files>
</Accordion>

<Accordion id="node-issues" title="已知的 Node.js 問題">
如果您遇到類似以下的 Turbopack 錯誤：

```
JSON file not found: FileSystemPath { ... path: "lib/locales/sources/file.json.json" }
```

這通常是因為不支援 `require(esm)` ([#3312](https://github.com/fuma-nama/fumadocs/issues/3312)) ，請升級至 Node.js 22 以上版本。

若您在 Node.js 23.1 上進行正式環境建置時遇到以下錯誤：

```
Could not find a production build in the '.next' directory.
```

這是已知問題，請參閱 [#1021](https://github.com/fuma-nama/fumadocs/issues/1021)。您可以將 Node.js 升級至 23.6.0 以上版本。
</Accordion>

<Accordion id="dynamic-route" title="使用動態路由會不會影響效能？">
只要設定了 `generateStaticParams`，Next.js 就會將動態路由轉換為靜態路由。
因此，其速度與靜態頁面一樣快。

您可以[啟用靜態匯出](/docs/next/deploying/static)，以產生靜態的建置輸出。
</Accordion>
</Accordions>

## 深入了解 [#learn-more]

剛開始接觸嗎？別擔心，我們非常歡迎您提出任何問題。

如果有任何令您困惑的地方，歡迎到 [Github Discussion](https://github.com/fuma-nama/fumadocs/discussions) 提供您的意見回饋！

### 撰寫內容 [#writing-content]

撰寫文件前，請務必閱讀：

<Cards>
<Card href="/docs/markdown" title="Markdown">
/docs/next/markdown" title="Markdown">
  Fumadocs 提供了一些額外功能，協助您撰寫內容。
</Card>

<Card href="/docs/navigation" title="導覽">
/docs/next/navigation" title="導覽">
  了解如何自訂導覽結構。
</Card>

<Card href="/docs/page-conventions" title="頁面 Slug 與頁面樹">
/docs/next/page-conventions" title="頁面 Slug 與頁面樹">
  了解如何組織內容。
</Card>

<Card href="/docs/ui/components" title="元件" description="瀏覽所有可用元件，讓您的文件更豐富" />
</Cards>

### 特殊需求 [#special-needs]

<Cards>
<Card href="/docs/deploying/static" title="設定靜態匯出" description="了解如何為您的文件網站啟用靜態匯出">
/docs/next/deploying/static
</Card>

<Card href="/docs/internationalization" title="國際化" description="了解如何啟用 i18n">
/docs/next/internationalization
</Card>

<Card href="/docs/ui/theme" title="色彩主題" description="為 Fumadocs UI 加入主題" />

<Card href="/docs/ui/layouts" title="版面配置" description="自訂您的 Fumadocs UI 版面配置" />
</Cards>