图片与静态资源

Vergil 沿用 Astro 官方的做法：图片集中存放，构建时自动压缩、转 WebP、写入宽高。在此基础上加了一个 @img/ 别名，不管文章放在哪一层目录，引用路径都一样。

两种引用方式

原则是：内容相关的图放 src/assets/，public/ 只放站点本身的文件。 外链 https://... 在两类位置都能用。

目录全景

src/assets/img/                  ← @img/ 指向这里├── blog/<文章名>/                  博客文章的图├── projects/<项目名>/              项目的图├── pages/<页面名>/                 独立页面的图，比如 pages/about/├── docs/<知识库>/                  知识库的图，含 _meta.md 的封面├── albums/<相册名>/                相册的封面和照片├── series/<专栏名>/                专栏封面├── moments/<文件名>/               图文动态的图└── thoughts/<文件名>/              想法的图src/assets/videos/                  相册主题的背景视频，构建时带内容哈希输出public/├── favicon.svg、manifest.json      必须放在根路径的文件└── assets/                       ← /assets/ 指向这里    ├── site/                        站点图：头像、分享卡片图    ├── defaults/                    主题的默认图：开屏背景、动态页横幅，没配置时使用    └── <按需建>/                    private 加密内容用到的图

src/assets/img/ 下的目录名和 src/content/ 下的目录名一一对应。

@img/：内容里的图

图片放在 src/assets/img/<载体>/<内容名>/，引用写 @img/<载体>/<内容名>/<图片名>。

• 载体是 src/content/ 下的目录名：blog、projects、pages、docs、albums、series、moments、thoughts。
• 内容名是文件名去掉 .md。放在专栏子目录里的文章也只取文件名，和文章 URL 的规则一致。
• 文档按知识库分：不同知识库里常有同名文件，所以写 @img/docs/<知识库>/<图片名>。

src/assets/img/blog/├── starrocks-compaction/│   └── trigger-flow.png└── 短链服务/    └── architecture.pngsrc/content/blog/├── starrocks-compaction.md      ![](@img/blog/starrocks-compaction/trigger-flow.png)└── 系统设计/    └── 短链服务.md              ![](@img/blog/短链服务/architecture.png)

主题自带的示例就是这样放的，可以照着改：

• 写第一篇文章：放在专栏子目录 搭建你的第一个站点/ 里的文章，含正文图片、banner 和 seo.image
• 山里的一个周末：普通文章，横幅、摄影框和画廊里的图都用 @img/
• 专栏「搭建你的第一个站点」的封面：src/assets/img/series/搭建你的第一个站点/cover.svg，在 专栏列表 里能看到效果
• 本页的这张图：知识库文档里的图片，放在 src/assets/img/docs/vergil-guide/

![山峰](@img/docs/vergil-guide/mountains.jpg)

@img/ 定义在 tsconfig.json 的 paths 里，由 Astro 原生解析。写法和文章所在的目录无关，文章挪进专栏子目录，路径也不用改。

正文里：

![Compaction 触发流程](@img/blog/starrocks-compaction/trigger-flow.png)

frontmatter 里声明为图片类型的字段也能用。@ 开头的值在 YAML 里必须加引号，否则构建报错：

---
seo:
  image:
    src: '@img/blog/starrocks-compaction/cover.jpg'
---

支持 @img/ 的字段：博客和文档的 banner，专栏的 cover，博客、页面、项目的 seo.image.src，知识库 _meta.md 的 cover，相册的 cover 和 images[].src，图文动态 JSON 里的 images 和 linkCard.image，想法正文里的图片。

banner 和专栏 cover 也兼容 / 开头的 public/ 路径和外链，老内容不用改也能用。

构建后图片输出到 /_astro/，文件名带内容哈希，比如 trigger-flow.TDdz2LGr.webp，并自动带上 width、height 和 loading="lazy"。

内容指令里的图

所有内容指令里的图片都和正文图片一样，支持 @img/、相对路径和外链，本地图片会被优化：

::image{src="@img/blog/my-post/a.png" alt="架构图"}

:::video{src="https://example.com/v.mp4" poster="@img/blog/my-post/poster.jpg"}
:::

例外只有一个：private 加密内容。它的正文在构建时被加密成字符串，里面的图片没法交给 Astro，只能写外链或 /assets/ 路径。

/assets/：站点的图

public/assets/ 放站点本身用到的图，以及 private 加密内容里的图。这里的文件原样输出，不会被压缩。

站点图片都在配置里写路径：

换成自己的图，同名覆盖，或者把配置里的路径改成你自己的文件。

写作时不用管规则

写的时候图片放哪、路径怎么写都行，比如 Typora 粘贴截图生成的相对路径。pnpm build 会先运行 pnpm images:organize，把图片挪到规则目录、引用改成 @img/，再开始构建。

想在编辑器里修改已经整理过的文章时，先展开：

pnpm images:expand

它把 @img/xxx 改成指向 src/assets/img/xxx 的相对路径，比如 ../../assets/img/blog/my-post/a.png，Typora、VS Code 就能预览了。图片文件不会移动。展开后的写法 pnpm dev 和 pnpm build 都能正常解析，下次 pnpm build 时会自动改回 @img/。

展开范围是博客、项目、页面、知识库、相册、专栏、想法。图文动态是 JSON，编辑器预览不了，保持 @img/ 写法。

用 pnpm images:organize 整理

已经写好的内容里，图片如果还散在别处（相对路径、public/ 下），运行一次就能按上面的规则整理好：

pnpm images:organize

它会：

1. 找出博客、项目、页面、知识库、相册、专栏、想法、图文动态里还没用 @img/ 的本地图片引用，包括正文图片，banner、cover、seo.image.src、相册 images[].src、图文动态的 images，以及内容指令里的图片
2. src/assets/img/ 之外的图片移动到 src/assets/img/<载体>/<内容名>/；已经在 src/assets/img/ 里的图片不挪，只统一写法
3. 把引用改成 @img/...，frontmatter 里自动加引号
4. 最后自动跑一次 pnpm images:check

几种特殊情况：

不会做的事：不删除任何图片，没被引用的图原地不动；不处理 private 加密内容里的图片；代码块和行内代码里的写法示例不动。

命令直接修改文件，建议在 git 工作区干净的时候运行，整理完用 git diff 看一遍改动。已经整理好的内容再运行一次，不会有任何变化。

整理结果里如果有失效引用，只会列出来，不会让命令失败，所以不会挡住 pnpm build。要在 CI 里把失效引用当成错误，用 pnpm images:check。

用 pnpm images:check 体检

仓库自带一个图片检查脚本，只读不写，不会删除或移动任何文件：

pnpm images:check

它会报告五类问题：

只有「引用失效」会让命令以非零状态退出，适合放进 CI。其余几类只是提示，尤其是「暂未引用」的图，可能是留着以后用的，脚本不会建议删除。

体积阈值默认 500KB，要调整就改 scripts/check-images.mjs 顶部的 MAX_KB。