# Fumadocs (Framework Mode, Astro): 匯出 EPUB
URL: /zh-TW/docs/astro/guides/export-epub
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/(framework)/[framework]/guides/export-epub.zh-TW.mdx

將您的文件匯出為 EPUB 格式，供電子閱讀器閱讀

## 簡介 [#introduction]

EPUB 整合可讓您將 Fumadocs 文件匯出為 EPUB 檔案，方便讀者下載您的文件，並在電子閱讀器、平板電腦或任何支援 EPUB 的應用程式上閱讀。

此整合會將您的 MDX 內容轉換為 HTML、解析圖片，並產生符合標準且附有目錄的 EPUB 檔案。

## 設定 [#setup]

Fumadocs CLI 可以自動幫您完成設定。它會建立一個受 `EXPORT_SECRET` 保護的匯出路由，並啟用 `includeProcessedMarkdown`：

```package-install
npx @fumadocs/cli feature epub
```

或手動設定：

### 安裝 [#installation]

```npm
npm install fumadocs-epub
```

### 啟用處理後的 Markdown [#enable-processed-markdown]

若要匯出 EPUB，必須在整合選項中啟用 `includeProcessedMarkdown`：

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import fumadocs from '@fumadocs/astro';

export default defineConfig({
  integrations: [
    fumadocs({
      includeProcessedMarkdown: true, // [!code ++]
    }),
  ],
});
```

### 建立匯出路由 [#create-export-route]

`createEpubExportAPI` 會建立路由處理常式，並以 `secret` 加以保護：若請求未帶有相符的 `Authorization: Bearer <secret>` 標頭，就會遭到拒絕；若未設定密鑰，路由則會回應 `503`。

```ts title="src/pages/export/epub.ts"
import type { APIRoute } from 'astro';
import { source } from '@/lib/source';
import { createEpubExportAPI } from 'fumadocs-epub';
import { getSecret } from 'astro:env/server';

// 每次請求時算繪，需要轉接器
export const prerender = false;

const api = createEpubExportAPI({
  source,
  title: 'My Documentation',
  secret: getSecret('EXPORT_SECRET'),
});

export const GET: APIRoute = ({ request }) => api.GET(request);
```

若要提供公開端點，或想自行產生檔案 (例如在指令碼中) ，請直接呼叫 `exportEpub()` 並回傳緩衝區。

### 使用 CLI [#using-the-cli]

您也可以透過 Fumadocs CLI 匯出 EPUB：

```bash
fumadocs export epub --framework astro
```

此指令會從執行於連接埠 `4321` (或 `PORT`) 的伺服器取得檔案，並以 `EXPORT_SECRET` 環境變數作為密鑰。

## 選項 [#options]

`exportEpub` 與 `createEpubExportAPI` 皆接受下列選項：

| 選項             | 型別                   | 說明                                                 |
| -------------- | -------------------- | -------------------------------------------------- |
| `title`        | `string`             | **必填。** 書名                                         |
| `author`       | `string \| string[]` | 作者名稱 (可為多位) 。預設：`'anonymous'`                      |
| `description`  | `string`             | 書籍說明                                               |
| `language`     | `string`             | 語言代碼 (例如 `'en'`) 。預設：`'en'`                        |
| `publisher`    | `string`             | 出版者名稱。預設：`'anonymous'`                             |
| `isbn`         | `string`             | ISBN                                               |
| `cover`        | `string`             | 封面圖片。支援 `file://`、`http(s)://`、`/public/...` 或相對路徑 |
| `outputPath`   | `string`             | 若有設定，除了回傳緩衝區外，也會將 EPUB 寫入檔案                        |
| `includePages` | `(page) => boolean`  | 篩選：只納入此函式回傳 `true` 的頁面                             |
| `excludePages` | `(page) => boolean`  | 篩選：排除此函式回傳 `true` 的頁面                              |
| `css`          | `string`             | EPUB 的自訂 CSS。若省略則使用 `defaultEpubStyles`            |
| `publicDir`    | `string`             | 用於解析 `/public/...` 圖片路徑的 public 目錄。預設：`./public`   |

`createEpubExportAPI` 另外多了兩個選項：`secret` (必填，用於保護路由) 與 `filename` (下載的檔案名稱，預設為 `docs.epub`) 。

### 自訂 CSS [#custom-css]

您可以覆寫預設的 EPUB 樣式：

```ts
import { exportEpub, defaultEpubStyles } from 'fumadocs-epub';

const buffer = await exportEpub({
  source,
  title: 'My Docs',
  author: 'Me',
  css: `${defaultEpubStyles}
/* 自訂覆寫樣式 */
body { font-size: 1.1em; }
`,
});
```

### 篩選頁面 [#filtering-pages]

使用 `includePages` 與 `excludePages` 控制要匯出哪些文件：

```ts
const buffer = await exportEpub({
  source,
  title: 'My Docs',
  author: 'Me',
  // 僅納入 /docs/getting-started 底下的文件
  includePages: (page) => page.path.startsWith('getting-started'),
  // 排除特定路徑
  excludePages: (page) => page.path === 'changelog',
});
```

### 圖片解析 [#image-resolution]

MDX 中的圖片會自動解析：

* **相對路徑** (例如 `./image.png`) ：以頁面檔案所在位置為基準解析
* **公開路徑** (例如 `/og.png`) ：從 `public` 目錄解析
* **遠端 URL** (例如 `https://...`) ：原樣嵌入