相册创建

相册存放在 src/content/albums/ 目录下，使用 Markdown 格式（.md）。

最小示例

---
title: '我的摄影集'
date: 2024-01-01
cover: '@img/albums/my-album/cover.jpg'
images:
  - src: '@img/albums/my-album/photo1.jpg'
    alt: '日落'
    caption: '海边日落'
---

这里是相册的介绍文字。

字段说明

字段	必填	说明
`title`	是	相册标题
`description`	否	相册简介，显示在列表页
`date`	是	相册日期，用于排序
`cover`	否	封面图路径，相对于当前文件
`images`	否	照片数组（详见下方）
`tags`	否	标签数组
`theme`	否	主题：`golden` 或 `seasons`，默认 `golden`
`layout`	否	布局：`grid`/`masonry`/`timeline`/`carousel`，默认 `grid`
`photoFit`	否	图片填充：`cover`/`contain`/`auto`，默认 `cover`
`background`	否	页面背景色，十六进制值
`accent`	否	强调色，十六进制值
`seasonFilter`	否	是否启用季节过滤（仅 `seasons` 主题），默认 `false`
`seasonDefault`	否	默认展示的季节：`spring`/`summer`/`autumn`/`winter`

图片配置

images 是一个数组，每个元素支持以下字段：

字段	必填	说明
`src`	是	图片路径，相对于当前文件
`alt`	否	图片替代文字
`caption`	否	图片说明，显示在图片下方
`season`	否	季节标记：`spring`/`summer`/`autumn`/`winter`
`featured`	否	是否精选，默认 `false`
`exif`	否	EXIF 信息对象

EXIF 信息

images:
  - src: '@img/albums/my-album/photo.jpg'
    alt: '示例照片'
    caption: '黄昏时分'
    exif:
      camera: 'Sony'
      model: 'A7M4'
      focal: '35mm'
      aperture: 'f/1.4'
      shutter: '1/500s'
      iso: '200'
      datetime: '2024-01-15 18:30'

EXIF 字段	说明
`camera`	相机品牌
`model`	相机型号
`lens`	镜头型号
`focal`	焦距
`aperture`	光圈
`shutter`	快门速度
`iso`	ISO 感光度
`datetime`	拍摄时间

拍摄参数显示在哪里

这一点容易被忽略：相册里的拍摄参数不是一直显示的。

在桌面端，参数藏在照片的悬停浮层里，鼠标移到照片上才会出现。在触屏设备上没有悬停这个动作，所以参数会常驻显示。两套主题显示的字段不完全一样：

主题	显示的字段
Golden	品牌、机型、镜头、焦距、光圈、快门、ISO
Seasons	品牌、镜头、焦距、光圈

想直接看效果，去演示站的四季物语把鼠标移到任意一张照片上。

在文章里单独展示一张照片

如果只是想在文章中间插一张带参数的照片，不必建相册，用 photo 指令就够了。它会生成模糊背景加居中照片的版式，底部带一条品牌与参数信息栏。

35mm f/1.4 1/125s 800

写法：

:::photo{src="@img/blog/my-post/lake.jpg" alt="山间湖泊" brand="fujifilm" model="X-T5"
  focal="35mm" aperture="f/1.4" shutter="1/125s" iso="800" datetime="2026-04-12 17:40"}
:::

属性	说明
`src`	图片地址，必填。支持 `@img/`、相对路径和外链，本地图片构建时会被优化
`alt`	替代文字
`brand`	相机品牌，内置二十个厂商的标志，写小写英文名即可，例如 `fujifilm`、`canon`、`nikon`、`sony`、`leica`、`apple`
`logo`	单独指定用哪个品牌的标志，不填则跟随 `brand`
`model`	机型
`focal` / `aperture` / `shutter` / `iso`	焦距、光圈、快门、感光度，显示在信息栏右侧
`datetime`	拍摄时间
`fancybox`	设为 `false` 可关闭点击放大

品牌名不在内置列表里也没关系，brand 会原样显示成文字。

完整示例

---
title: '四季物语'
description: '记录四季流转中的自然与人文景观'
date: 2024-06-01
theme: 'seasons'
layout: 'grid'
photoFit: 'contain'
background: '#0d0d12'
accent: '#C8A464'
seasonFilter: true
seasonDefault: 'summer'
cover: '@img/albums/my-album/hero.jpg'
images:
  - src: '@img/albums/my-album/spring/cherry.jpg'
    alt: '樱花盛开'
    caption: '春天的第一缕温暖'
    season: 'spring'
    featured: true
    exif:
      camera: 'Sony A7M4'
      focal: '85mm'
      aperture: 'f/1.8'
      shutter: '1/500s'
      iso: '200'
  - src: '@img/albums/my-album/summer/beach.jpg'
    alt: '夏日海滩'
    caption: '阳光与海浪'
    season: 'summer'
tags: ['四季', '自然']
---

## 关于本期

这是一组以季节为主题的摄影作品集。

图片存放位置

相册的照片和封面放在 src/assets/img/albums/<相册名>/ 下，相册名就是相册 .md 的文件名。用 @img/ 别名引用：

src/assets/img/albums/  my-album/    cover.jpg    spring/      cherry.jpg    summer/      beach.jpgsrc/content/albums/  my-album.md

src/assets/img/albums/
  my-album/
    cover.jpg
    spring/
      cherry.jpg
    summer/
      beach.jpg

src/content/albums/
  my-album.md

---
cover: '@img/albums/my-album/cover.jpg'
images:
  - src: '@img/albums/my-album/spring/cherry.jpg'
---

@img/ 开头的值在 YAML 里必须加引号，否则 @ 会被当成保留字符，构建报错。

照片多的相册可以在相册目录下再按主题、季节分子目录，路径跟着写就行。整套图片规则见图片与静态资源。

Tip

不要使用 / 开头的绝对路径（如 /images/photo.jpg）。那是 public/ 下的文件，不会经过 Astro 的图片优化。

Astro 图片优化

Vergil 使用 Astro 内置的图片优化系统，相册中的 cover 和 images[].src 会在构建时自动进行以下处理：

格式转换 — 自动转换为 WebP/AVIF 等现代格式
尺寸适配 — 根据展示尺寸生成合适大小的图片
懒加载 — 页面外的图片延迟加载，提升首屏速度

因此，存放原始图片时无需预先压缩。建议：

使用原始分辨率的照片（构建时会自动压缩）
图片格式支持 JPG、PNG、WebP
单张图片文件大小建议不超过 10MB