charmbracelet/freeze：为代码与终端输出生成图片

项目用途

Freeze 用于为代码和终端输出生成图片，可输出 PNG、SVG 与 WebP 三种格式。它既能给代码文件生成带语法高亮的截图，也能通过 --execute 捕获终端命令的 ANSI 输出。项目内置交互式 TUI，方便直接调参预览。

基本用法

• 为代码生成图片：freeze artichoke.hs -o artichoke.png
• 捕获终端输出：使用 --execute 标志，例如 freeze --execute "eza -lah"。
• 交互式定制：freeze --interactive，配置会写入 $XDG_CONFIG/freeze/user.json，可用 freeze --config user 读取。

配图 1 为教程示意图；配图 2 为 Freeze 代码截图演示；配图 3 至配图 12 依次展示阴影、ANSI 输出、交互模式、Haskell 代码块、dracula 主题、8px 圆角、窗口控件、边框、内边距、外边距等不同定制效果。

可定制项与常用标志

来源列出以下标志（可用 freeze --help 查看全部）：

• -b, --background：填充背景色。
• -c, --config：基础配置文件或模板。
• -l, --language：指定代码语言。
• -m, --margin：为窗口添加外边距。
• -o, --output：.svg、.png、.jpg 的输出位置。
• -p, --padding：为代码添加内边距。
• -r, --border.radius：窗口圆角半径。
• -t, --theme：语法高亮主题。
• -w, --window：显示窗口控件（macOS 风格）。
• -H, --height：终端窗口高度。
• --border.width、--border.color：边框宽度与颜色。
• --shadow.blur、--shadow.x、--shadow.y：阴影高斯模糊与偏移。
• --font.family、--font.ligatures、--font.size、--font.file：字体族、连字、字号、嵌入字体文件（SVG 内嵌）。
• --line-height：相对字号的行高。
• --show-line-numbers：显示行号。
• --lines：捕获指定行范围（start,end）。

语言、主题与输出

• 语言：Freeze 会尽量根据文件名或内容自动识别语言，可用 --language 覆盖，例如 cat artichoke.hs | freeze --language haskell。
• 主题：用 --theme 切换配色，例如 freeze artichoke.hs --theme dracula。
• 输出：默认输出 out.svg，若被管道接收则输出到 stdout；支持 .svg、.png、.webp，也可一次多格式：freeze main.go --output out.{svg,png,webp}。

字体与排版

可指定字体族、字号与行高，默认 JetBrains Mono、14（px）、1.2（em）：

freeze artichoke.hs \
  --font.family "SF Mono" \
  --font.size 16 \
  --line-height 1.4

也可用 --font.file 嵌入 TTF、WOFF 或 WOFF2 字体文件，用 --font.ligatures 启用字体连字。

样式示例

• 行号：freeze artichoke.hs --show-line-numbers，配合 --lines 2,3 只捕获指定行。
• 圆角：freeze artichoke.hs --border.radius 8。
• 窗口控件：freeze artichoke.hs --window。
• 背景：freeze artichoke.hs --background "#08163f"。
• 高度：freeze artichoke.hs --height 400。
• 边框：freeze artichoke.hs --border.width 1 --border.color "#515151" --border.radius 8。
• 内边距与外边距：可传 1、2 或 4 个值，如 freeze main.go --padding 20（四边）、--padding 20,40（垂直、水平）、--padding 20,60,20,40（上、右、下、左）；外边距同理 --margin 20/20,40/20,60,20,40。
• 阴影：freeze artichoke.hs --shadow.blur 20 --shadow.x 0 --shadow.y 10。

截图 TUI

可使用 tmux capture-pane 截取 TUI 界面：先把 TUI 运行在 tmux 中并调整到想捕获的状态，然后用 capture-pane 抓取窗格并管道传给 freeze，例如：

hx # in a separate pane
tmux capture-pane -pet 1 | freeze -c full

配置文件

Freeze 支持通过 JSON 文件配置，用 --config / -c 传入；一般情况下所有 --flag 选项与配置文件的键值一一对应。内置若干可直接按名称使用的默认配置：

• base：简洁的代码截图。
• full：类似 macOS 的截图。
• user：使用 ~/.config/freeze/user.json。

示例：

freeze -c base main.go
freeze -c full main.go
freeze -c user main.go # alias for ~/.config/freeze/user.json
freeze -c ./custom.json main.go

示例配置内容：

{
  "window": false,
  "border": {
    "radius": 0,
    "width": 0,
    "color": "#515151"
  },
  "shadow": false,
  "padding": [20, 40, 20, 20],
  "margin": "0",
  "font": {
    "family": "JetBrains Mono",
    "size": 14
  },
  "line_height": 1.2
}

适用对象

需要在文档、博客、社交媒体、演示幻灯片中展示代码或终端输出效果的开发者、技术写作者与开源维护者；以及需要为 TUI 项目制作截图的命令行工具作者。

贡献与反馈

项目提供 contributing 指南；反馈渠道包括 Twitter、The Fediverse 与 Discord。Freeze 是 Charm 生态的一部分。

— 本文由 AI 根据公开来源辅助整理，命令、版本与许可证请在使用前到原始页面复核。