> For the complete documentation index, see [llms.txt](https://gitbook.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/blocks/insert-images.md).

# 图片

向页面添加图片或图片库，为深色模式添加图片变体，并按需调整图片大小和对齐方式

你可以将图片插入页面，然后选择它们的大小，以及是否左对齐、居中或右对齐。你还可以选择在图片块中添加替代文本和/或说明文字。

{% hint style="info" %}
**提示：** 为确保无障碍访问，我们建议为图片设置替代文本。
{% endhint %}

### 图片块示例 <a href="#example-of-an-image-block" id="example-of-an-image-block"></a>

<div align="center"><figure><img src="https://images.unsplash.com/photo-1446776709462-d6b525c57bd3?crop=entropy&#x26;cs=srgb&#x26;fm=jpg&#x26;ixid=M3wxOTcwMjR8MHwxfHNlYXJjaHwyfHxzcGFjZXxlbnwwfHx8fDE3MzMxOTY5NTR8MA&#x26;ixlib=rb-4.0.3&#x26;q=85" alt="A photograph taken from space looking back towards Earth. A satellite is in the foreground, and in the background is an ocean-covered part of our planet with patchy clouds."><figcaption><p>带说明文字的图片块示例</p></figcaption></figure></div>

### 上传图片

向内容中添加图片有两种方式：

1. 将图片从文件管理系统直接拖放到页面中的空白块里。
2. [添加图片块](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/blocks.md#inserting-a-new-content-block) 到页面，然后使用 **选择图片** 窗口右侧显示的侧边栏。

如果采用第二种方式，你可以选择上传文件、选择之前上传的文件、粘贴图片 URL，或使用内置搜索从 [Unsplash](https://unsplash.com/) 添加图片。

{% hint style="warning" %}
GitBook 允许你上传单个文件最大 100MB 的图片。
{% endhint %}

某个章节中的资源总数没有固定限制，但 GitBook 保留在滥用情况下封禁账号的权利。对于超过上传限制的文件，请将其存储在 Google Drive 或 Dropbox 等服务中，并从页面链接到它们。

动画 GIF 每个文件最多支持 200 帧。大文件——包括 GIF——会减慢页面加载速度，因此尽量避免直接上传大型文件。

#### 创建图片画廊

在图片块中添加多张图片会创建一个图片库。要执行此操作，请打开该块的 **选项菜单** <picture><source srcset="broken://files/QLUQj6waZRiK6FpSqrt6" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-23f3e8f05326b0d239d32d28bba99c1d46f204f7%2F25_01_10_options_light.svg?alt=media" alt="The Options menu icon in GitBook"></picture> 并选择 **添加图片…** 以再次打开 **选择图片** 侧边栏。

要从图片库中删除图片，请打开要删除图片上的 **编辑菜单** <picture><source srcset="broken://files/kN09oTFtAuyaxNIwWuCt" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-d28f11ed4dfafb06aa9c6ae92db8017d94014317%2F25_01_10_edit_icon_light.svg?alt=media" alt=""></picture> 并按下 **Delete ⌫** 键。

### 为浅色和深色模式添加图片 <a href="#light-and-dark-mode" id="light-and-dark-mode"></a>

你可以为已发布站点的浅色和深色模式版本设置不同的图片。GitBook 会根据访客所处的模式自动显示正确的图片。

要为深色模式添加图片，请将鼠标悬停在图片上，打开 **编辑菜单** <picture><source srcset="broken://files/kN09oTFtAuyaxNIwWuCt" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-d28f11ed4dfafb06aa9c6ae92db8017d94014317%2F25_01_10_edit_icon_light.svg?alt=media" alt=""></picture> 并点击 **替换图片** <picture><source srcset="broken://files/B8EhRVkFXw7nB8Q01UEZ" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-058c44f9175073421beb38f54db046e0f48de843%2F25_01_10_replace_image_icon_light.svg?alt=media" alt="The Replace image icon in GitBook"></picture>.

在下拉菜单中，选择 **为深色模式添加图片**。完成设置后，你可以在同一菜单中替换任一图片。

{% hint style="warning" %}
**注意：** GitBook 目前不支持在某些情况下使用浅色和深色模式图片，包括页面封面或 [卡片](https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/blocks/cards.md).
{% endhint %}

### 通过 GitHub/GitLab Sync 使用浅色和深色模式图片 <a href="#light-and-dark-mode-through-github-gitlab-sync" id="light-and-dark-mode-through-github-gitlab-sync"></a>

上的图片封面。你也可以通过 HTML 语法在 Markdown 中添加浅色和深色模式图片（`<picture>` 和 `<source>`).

对于块级图片，请使用 `<figure>` HTML 元素，并在其中使用 `<picture>` 和 `<source>` ：

```html
前面的文本

<figure>
  <picture>
    <source
      srcset="
        https://user-images.githubusercontent.com/3369400/139447912-e0f43f33-6d9f-45f8-be46-2df5bbc91289.png
      "
      media="(prefers-color-scheme: dark)"
    />
    <img
      src="https://user-images.githubusercontent.com/3369400/139448065-39a229ba-4b06-434b-bc67-616e2ed80c8f.png"
      alt="GitHub 标志"
    />
  </picture>
  <figcaption>说明文字</figcaption>
</figure>

后面的文本
```

对于行内图片（与文本处于同一行的图片），请使用 `<picture>` HTML 元素，并在其中使用 `<source>` ：

```html
图片前的文本
<picture
  ><source
    srcset="
      https://user-images.githubusercontent.com/3369400/139447912-e0f43f33-6d9f-45f8-be46-2df5bbc91289.png
    "
    media="(prefers-color-scheme: dark)" />
  <img
    src="https://user-images.githubusercontent.com/3369400/139448065-39a229ba-4b06-434b-bc67-616e2ed80c8f.png"
    alt="GitHub 标志"
 /></picture>
以及图片后的文本
```

{% hint style="warning" %}
**注意：** 我们目前尚不支持 [仅适用于 GitHub 的语法](https://github.blog/changelog/2021-11-24-specify-theme-context-for-images-in-markdown/) 通过 `#gh-dark-mode-only` 或 `#gh-light-mode-only`.
{% endhint %}

### 调整大小

要调整图像大小，请将鼠标悬停在图像上，然后打开 **“编辑”菜单** <picture><source srcset="broken://files/kN09oTFtAuyaxNIwWuCt" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-d28f11ed4dfafb06aa9c6ae92db8017d94014317%2F25_01_10_edit_icon_light.svg?alt=media" alt=""></picture>。点击 **“大小”** 按钮，从可用选项中更改图像大小。

<figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-3b8b303d26529bb63609ef087c19c9c9815dda05%2F25_12_10_image_resizing%402x.png?alt=media" alt="A GitBook screenshot showing how to resize an image"><figcaption><p>调整图片大小</p></figcaption></figure>

* **小** – 图像尺寸的 25%
* **中** – 图像尺寸的 50%
* **大** – 图像尺寸的 75%
* **适应** – 移除所有尺寸规格，并以原始大小显示图像；对于较大的图像，最大宽度限制为 **735** **像素** 。

如果你的图片比编辑器更宽，GitBook 会将图片宽度限制为编辑器宽度，并据此进行调整。

{% hint style="info" %}
**注意：** 在图库中调整图像大小，结果可能与调整单张图像大小不同。
{% endhint %}

### 通过 Git Sync 调整图片大小

如果你想更精确地控制图片大小，可以在 GitHub 或 GitLab 中使用 Markdown 指定确切尺寸。

导出图像时，我们使用 HTML 标签 `<img/>`。根据规范，我们可以使用 `width` 和 `height` 属性指定图像尺寸，这些属性只接受像素值，或由数字和 `%` 符号组成的值。\
\
以下是指定图像尺寸的有效写法：\
\
`<img width="100" />` 将图像宽度设为 100 像素\
`<img width="100%" />` 将图像设为全尺寸（但会受到编辑器的限制）

### 对齐图片

默认情况下，图片块会以完整大小居中显示图片。

要更改图像的对齐方式，请打开区块的 **“选项”菜单** <picture><source srcset="broken://files/QLUQj6waZRiK6FpSqrt6" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-23f3e8f05326b0d239d32d28bba99c1d46f204f7%2F25_01_10_options_light.svg?alt=media" alt="The Options menu icon in GitBook"></picture> 并选择所需的对齐方式。这只会影响宽度小于编辑器的图像，或已 [调整大小](#resizing).

### 为图片加框

你可以为图片块添加边框，让图片风格更统一，并在视觉上将其与周围内容区分开来。

<div data-with-frame="true"><figure><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-61de0988bf7e96f4e2bcc8e85c4f70bca626f781%2F25_10_06_image_frame_demo%402x.jpg?alt=media" alt="A black and white photograph of a lone figure walking across a stark white landscape"><figcaption><p>带框图片可以包含说明文字，并在说明文字后显示细微的网格背景。</p></figcaption></figure></div>

要为图像添加边框，请将鼠标悬停在图像上，打开区块的 **“选项”菜单** <picture><source srcset="broken://files/QLUQj6waZRiK6FpSqrt6" media="(prefers-color-scheme: dark)"><img src="https://2111890564-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FNkEGS7hzeqa35sMXQZ4X%2Fuploads%2Fgit-blob-23f3e8f05326b0d239d32d28bba99c1d46f204f7%2F25_01_10_options_light.svg?alt=media" alt=""></picture> 并启用 **“带边框”** 开关。

{% hint style="info" %}
**提示：** 区块中只有单张图像可以添加边框。包含多张图像的图像区块和行内图像均无法添加边框。
{% endhint %}

### Markdown 表示

```markdown
//简单块
![](https://gitbook.com/images/gitbook.png)

//带说明文字的块
![GitBook 标志](https://gitbook.com/images/gitbook.png)

//带替代文本的块

<figure><img src="https://gitbook.com/images/gitbook.png" alt="GitBook 标志"></figure>

//带说明文字和替代文本的块

<figure><img src="https://gitbook.com/images/gitbook.png" alt="GitBook 标志"><figcaption><p>GitBook 标志</p></figcaption></figure>

// 带框图片块

<div data-with-frame="true"><img src="https://gitbook.com/images/gitbook.png" alt="GitBook 标志"></div>

//带说明文字的深浅色模式不同图片块

<figure>
  <picture>
    <source srcset="https://user-images.githubusercontent.com/3369400/139447912-e0f43f33-6d9f-45f8-be46-2df5bbc91289.png" media="(prefers-color-scheme: dark)">
    <img src="https://user-images.githubusercontent.com/3369400/139448065-39a229ba-4b06-434b-bc67-616e2ed80c8f.png" alt="GitHub 标志">
  </picture>
  <figcaption>说明文字</figcaption>
</figure>
```

### 为什么我的图片没有加载？

“无法加载图片”错误表示该图片在其源头已被更改或删除。如果你是通过 URL 嵌入图片而不是上传它，GitBook 依赖于该 URL——如果图片在源站移动或消失，就会停止在你的页面上显示。

要解决此问题，请直接将图片上传到 GitBook，或在图片位置变更后更新 URL。你从一个章节复制图片到另一个章节时也可能出现该错误，因为每个章节都有自己的文件目录——请在新章节中重新上传该图片。

您可以在 **“媒体库”** 标签页中查看上传到某个分区的所有文件，该标签页位于目录顶部的 **“页面”** 旁边。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://gitbook.com/docs/documentation/zh/chuang-jian-nei-rong/blocks/insert-images.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
