# Fumadocs Core (the core library of Fumadocs): Remark Image
URL: /zh-TW/docs/headless/mdx/remark-image
Source: https://raw.githubusercontent.com/fuma-nama/fumadocs/refs/heads/main/apps/docs/content/docs/headless/mdx/remark-image.zh-TW.mdx

為圖片加上尺寸屬性。

這是一個 remark 外掛，會為您的圖片元素加上 `width` 與 `height` 屬性；在 Next.js 及部分其他框架中，必須具備這兩個屬性才能進行圖片最佳化 (Image Optimization) 。

## 使用方式 [#usage]

Fumadocs MDX 預設會啟用此功能。您可以透過 `remarkImageOptions` 傳入選項。無論使用 unified 或 Sätteri，選項皆相同。

支援：

* 本機圖片
* 外部 URL
* Next.js 靜態匯入

### 運作原理 [#how-it-works]

使用 `useImport` 時，本機圖片會轉換為**靜態匯入**，交由您的打包工具處理。Fumadocs MDX 預設會啟用此功能，但 `dynamic` 集合除外。
在 Next.js 上，這些圖片會由內建的圖片載入器處理，並支援 Next.js Image 的 `placeholder` 選項。

其他情況下，則會透過檔案系統或 HTTP 請求下載圖片，以取得圖片尺寸。

<Callout type="warn">
請勿傳入不受信任的圖片 URL。這些圖片會在編譯時被擷取，私有主機上的圖片也不例外。設定 `external: false` 即可略過外部圖片。
</Callout>

### 選項 [#options]

### RemarkImageOptions

| Prop           | Type                                                                     | Description                                                                                                                                                                                                                  |
| -------------- | ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicDir?`   | `string \| undefined`                                                    | Directory or base URL to resolve absolute image paths                                                                                                                                                                        |
| `placeholder?` | `"blur" \| "none" \| undefined`                                          | Preferred placeholder type, only available with `useImport` + local images. Default: `'none'`                                                                                                                                |
| `onError?`     | `"error" \| "hide" \| "ignore" \| ((error: Error) => void) \| undefined` | Define how to handle errors when fetching image size. - `error` (default): throw an error. - `ignore`: do absolutely nothing (Next.js Image component may complain). - `hide`: remove that image element. Default: `'error'` |
| `useImport?`   | `boolean \| undefined`                                                   | Import images in the file, and let bundlers handle it. ```tsx import MyImage from "./public/img.png"; <img src={MyImage} /> ``` When disabled, `placeholder` will be ignored. Default: `true`                                |
| `external?`    | `ExternalImageOptions \| undefined`                                      | Fetch image size of external URLs Default: `true`                                                                                                                                                                            |

### 範例：使用匯入 [#example-with-imports]

```mdx
![Hello](/hello.png)
![Test](https://example.com/image.png)
```

輸出結果：

```mdx
import HelloImage from './public/hello.png';

<img alt="Hello" src={HelloImage} />
<img alt="Test" src="https://example.com/image.png" width="1980" height="1080" />
```

其中 `./public/hello.png` 指向 public 目錄中的圖片。

### 範例：不使用匯入 [#example-without-imports]

若使用 Next.js，您可以停用本機圖片的靜態匯入。

```ts tab="unified" title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';

export default defineConfig({
  mdxOptions: {
    remarkImageOptions: {
      useImport: false,
    },
  },
});
```

```ts tab="Sätteri" title="source.config.ts"
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';

export const docs = defineDocs({
  docs: { compiler: 'satteri' },
});

export default defineConfig({
  satteriOptions: {
    remarkImageOptions: {
      useImport: false,
    },
  },
});
```

```mdx
![Hello](/hello.png)
![Test](https://example.com/image.png)
```

輸出結果：

```mdx
<img alt="Hello" src="/hello.png" width="1980" height="1080" />
<img alt="Test" src="https://example.com/image.png" width="1980" height="1080" />
```

### 範例：相對路徑 [#example-relative-paths]

啟用 `useImport` 後，您可以使用相對路徑來引用本機圖片。

```mdx
![Hello](./hello.png)
```

請注意，若停用 `useImport`，此用法**將無法運作**。
除非您已在程式碼中匯入圖片，否則 Next.js 不會將其加入公開資源。
至於 public 目錄中的圖片，您可以直接引用，無須使用相對路徑。

### 範例：public 目錄 [#example-public-directory]

自訂 public 目錄的路徑。

```ts tab="unified" title="source.config.ts"
import { defineConfig } from 'fumadocs-mdx/config';
import path from 'node:path';

export default defineConfig({
  mdxOptions: {
    remarkImageOptions: {
      publicDir: path.join(process.cwd(), 'dir'),
    },
  },
});
```

```ts tab="Sätteri" title="source.config.ts"
import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
import path from 'node:path';

export const docs = defineDocs({
  docs: { compiler: 'satteri' },
});

export default defineConfig({
  satteriOptions: {
    remarkImageOptions: {
      publicDir: path.join(process.cwd(), 'dir'),
    },
  },
});
```

`publicDir` 也可以設為基礎 URL，例如 `https://my-cdn.com/images`。