记录使用 Astro 搭建博客的过程中的一些使用技巧，包括图片优化、代码高亮等等。

博客源代码：chensoul.github.io

图片优化

参考 Photosuite：一个为博客而生的图片处理方案，使用 Photosuite 优化博客图片。

使用 markdown 语法设置图片

![example-picture](example-picture.webp)

注意图片路径前面没有 /，图片地址是相对路径（推荐与文章 slug 一致：{slug}/01.webp）。Photosuite 会将相对路径拼到 imageBase 后（见 astro.config.ts）。

本文中的实际示例图使用站内绝对路径，避免构建文档时去请求外部 EXIF 服务。

example-picture

如果使用绝对路径，比如 ![example-picture](/images/astro-theme-tips/01.webp)，Photosuite 不会进行替换。 渲染后的 html 如下：

<div class="photosuite-item"><a href="/images/example-picture.webp" data-fancybox="markdown">
  <img src="/images/example-picture.webp" alt="example-picture" loading="lazy" decoding="async"></a>
  <div class="photosuite-caption">example-picture</div>
</div>

也可以将 2 个或者 3 个图片排列到一起：

![example-picture](example-picture.webp)
![example-picture](example-picture.webp)


![example-picture](example-picture.webp)
![example-picture](example-picture.webp)
![example-picture](example-picture.webp)

astro.config.ts 中配置

astro.config.ts
photosuite({
  scope: '#article',
  imageBase: "https://cos.chensoul.cc/images",
  exif: {
      enabled: true,
      fields: [
        'Model',            // Camera Model
        'LensModel',        // Lens Model
        'FocalLength',      // Focal Length
        'FNumber',          // Aperture
        'ExposureTime',     // Shutter Speed
        'ISO',              // ISO
        'DateTimeOriginal'  // Date Original
      ],
      separator: ' · '      // Separator
    },
}),

https://cos.chensoul.cc/images 对应的是 obs 存储里面的 images 目录，这里我使用的是 Cloudflare R2 对象存储。cos.chensoul.cc 是对象存储桶（桶名称为 cos）对应的自定义域名，该存储桶下目前主要有：

  • dist：脚本库等资源
  • images：博客配图与统一图标目录 public/images/_favicons/（分类/列表用小图标，以及邻居 Feeds 抓取的站点图标），同属一棵目录树

仓库里使用 rclone 将 public/images 整棵同步到 r2:cos/images 即可。

使用 Rclone 上传图片

安装和配置 rclone：

Terminal window
brew install rclone
rclone config file

~/.config/rclone/rclone.conf 文件如下：

~/.config/rclone/rclone.conf
[r2]
type = s3
provider = Cloudflare
access_key_id = xxxx
secret_access_key = xxxxx
endpoint = https://2e1980a0ef43f57b920ea28cdf9d38d1.r2.cloudflarestorage.com
acl = private
no_check_bucket = true

操作桶和对象：

Terminal window
rclone tree r2:cos


# 同步到桶里的子目录，例如 cos 桶下的 images（含 _favicons/）。不删远程多余文件（默认就是这样）, -P 显示进度
rclone sync public/images r2:cos/images -P


# 看会同步哪些文件，不真正执行（试跑）
rclone sync public/images r2:cos/images -P --dry-run


# 多线程、显示传输进度
rclone sync public/images r2:cos/images -P --transfers 4

图片转 WebP

仓库里的 scripts/convert-to-webp.mjs（sharp）只做一件事：把 jpg/png 转成同名 .webp，并在一条流水线里先做 EXIF 旋转、长边超过 1920px 时等比缩小，再编码。

把 public/images 下所有 jpg/png 转成 webp（转完后删除原图）：

Terminal window
pnpm run convert-to-webp

只转换指定目录：

Terminal window
node scripts/convert-to-webp.mjs public/images/某子目录

保留原图，只多出一份 .webp：

Terminal window
pnpm run convert-to-webp -- --keep
# 或指定目录
node scripts/convert-to-webp.mjs public/images --keep

说明：

  • 只处理 jpg / jpeg / png，已经是 webp 的会跳过。
  • 输出为同名 .webp（如 a.jpg → a.webp）。
  • 会按 EXIF 自动旋转；长边超过 1920px 会先等比缩小再转 webp。
  • 不加 --keep 时会在转换成功后删除原图；若文章或代码里还在用 /images/xxx.jpg，需要改成 .webp 或先加 --keep 再逐步改引用。

列表 favicon（分类 / 站点图标）

在 frontmatter 中使用 favicon 字段，资源放在 public/images/_favicons/。常用写法是短文件名（解析为 /images/_favicons/该文件）；也可写完整根路径或外链。详见 PostUtils.resolveFaviconRef 与 Card.astro 中的 buildListFaviconSrc。

favicon: "astro.svg"

构建 URL 的要点：

  • favicon 为空：取 /images/_favicons/{首个分类}.svg，无分类则用 blank.svg
  • http(s)://：原样
  • 短文件名或 /images/...：按规则解析后，根相对且以 /images/ 开头的在生产环境可拼接 SITE.imageConfig.imagesUrl

config.ts 中定义了图片的 CDN 地址 https://cos.chensoul.cc

config.ts
imageConfig: {
    imagesUrl: "https://cos.chensoul.cc",
}

提示：使用 convertio 网站可以将图片转换为 SVG，然后使用 SVG Viewer 可以调整 SVG 大小，最后作为文章的缩略图。

代码高亮

Expressive Code 对静态架构非常友好，只要你的博客支持 Rehype 插件，就可以安装使用。

功能语法示例说明
标题title="app.ts"显示编辑器标签标题
语法高亮（ANSI）ansi渲染 ANSI 终端转义
行标注（高亮）{3,5-9}高亮第 3 行与 5–9 行
行标注（新增）ins={4-6}以“新增”样式高亮
行标注（删除）del={7,12}以“删除”样式高亮
行标注 + 标签ins={"Init":3-6}为 3–6 行添加引用标签
内联标注（文本）ins="inserted" del="deleted"高亮匹配到的片段
内联标注（正则）ins=/foo$.+$/用正则匹配片段
折叠区块collapse={1-5,12-14}折叠多段代码
行号开关showLineNumbers需安装行号插件
起始行号startLineNumber=5从第 5 行开始计数
自动换行wrap自动换行
悬挂缩进wrap hangingIndent=2换行时额外缩进 2 列
不保留缩进wrap preserveIndent=false换行后不缩进

示例：

示例
```go title="main.go" {17-20,22} del={14} ins={15,4-7} collapse={2-7} "rand.Seed(time.Now().UnixNano())"
func greet(id int, wg *sync.WaitGroup) {
 defer wg.Done()


 delay := time.Duration(rand.Intn(3000)) * time.Millisecond
 time.Sleep(delay)


 fmt.Printf("#%d Ping %v\n", id, delay)
}


func main() {
 rand.Seed(time.Now().UnixNano())


 var wg sync.WaitGroup
  numGoroutines := 10
 numGoroutines := 5


 for i := 1; i <= numGoroutines; i++ {
  wg.Add(1)
  go greet(i, &wg)
 }


 wg.Wait()
}
```

效果：

main.go
func greet(id int, wg *sync.WaitGroup) {
6 collapsed lines
  defer wg.Done()


  delay := time.Duration(rand.Intn(3000)) * time.Millisecond
  time.Sleep(delay)


  fmt.Printf("#%d Ping %v\n", id, delay)
}


func main() {
  rand.Seed(time.Now().UnixNano())


  var wg sync.WaitGroup
  numGoroutines := 10
  numGoroutines := 5


  for i := 1; i <= numGoroutines; i++ {
    wg.Add(1)
    go greet(i, &wg)
  }


  wg.Wait()
}