Caveman：用 Common Lisp 打造极简静态博客的返璞归真之路

写博客这些年，我越来越发现一个反直觉的现象：工具越复杂，写东西的欲望反而越低。编辑器装了一堆插件，静态站点生成器配了十几项参数，主题换了一个又一个，结果真正花在写作上的时间少得可怜。直到我遇到 Caveman，这个号称“死简单”的静态站点生成器，才算是找到了那种“回到原始洞穴，专心烤肉”的感觉。

Caveman 是一个用 Common Lisp 编写的静态博客生成器，它的核心理念就是“无理念”：不需要配置文件，不需要主题系统，不需要命令行参数，甚至连 Markdown 渲染都不内置。你写了什么模板，它就原样输出什么模板；你在哪个目录放文件，它就在哪个目录生成文件。它把“极简”做到了几乎只剩骨架的程度，但恰恰是这副骨架，让使用者能完全掌控自己的发布流程。

这篇文章想认真聊聊 Caveman 的设计思路、实际搭建过程，以及我在使用中踩过的坑。适合两类人看：一类是厌倦了 Node 生态和 Ruby 生态的折腾派，想试试 Lisp 世界里的另一个选择；另一类是纯写作者，想找一个不会被框架绑架的、干干净净的发布方案。

1. 项目整体设计与思路拆解

1.1 Caveman 在静态站点生成器里的“生态位”

如果把常见的静态生成器比作交通工具，Hugo 和 Jekyll 就是自动挡 SUV，功能齐全、上手就能跑，但发动机舱里塞满了你看不懂的零件。Caveman 更像一辆手动挡老爷车，没有倒车雷达没有导航，方向盘和油门清清楚楚，坏了你打开引擎盖就能修。

我从 2016 年开始折腾个人站，经历过 WordPress 的时代，也尝试过 Hexo 和 Hugo。这些工具的共同问题是：它们都内置了一套“你想要什么”的假设。Hugo 觉得你肯定想要分类、标签、分页、RSS，于是全都给你装上；Jekyll 觉得你肯定想要 Liquid 模板语言，于是你就得学一套非 Python 非 Ruby 的语法。这些假设本身没有错，但如果你只是想在网页上贴一些文字，它们就是负担。

Caveman 的设计哲学恰恰相反。它只做三件事：递归读取 content 目录下的模板文件，把带 .meta 文件的页面填充数据，然后把结果写到 output 目录。除此之外什么都不管。没有内置主题，没有分页逻辑，没有标签系统。你不需要学习任何框架特有的概念，因为整个系统只有“模板”和“元数据”这两个概念。

这种设计带来的第一个好处是：学习成本几乎为零。我从下载源码到跑出第一版页面，大概用了不到半小时，其中大半时间花在安装 Common Lisp 环境上。第二个好处是：站点结构完全由你决定。所有文件之间的链接都是手写的相对路径，所以你可以自由设计你的目录结构，想怎么组织就怎么组织。

当然，代价也很明显。Caveman 没有现成的主题市场，没有一键部署的集成插件，连语法高亮都要自己想办法。如果你需要的是“十分钟搭出漂亮博客”，它绝对不适合你。但如果你想理解静态站点的本质，或者想建一个完全属于自己、没有任何框架痕迹的站点，它几乎是完美的教学工具和实用工具。

1.2 为什么选择 Common Lisp 作为实现语言

这一点可能是 Caveman 最劝退的地方，但也是它最有趣的地方。Common Lisp 是一门有四十多年历史的老语言，和 Python、JavaScript 相比，它的社区规模小得可怜，现代 Web 开发相关的工具也少。但恰恰是这个“老古董”背景，给了 Caveman 一些独特的东西。

首先，Common Lisp 里一切皆可交互。你可以在 REPL（读-求值-打印循环，也就是 Lisp 的命令行交互环境）里一条条执行构建函数，观察每一步生成的文件，甚至可以修改正在运行的构建过程。这种体验用 Python 写静态生成器也是有的，但 Lisp 的 REPL 更彻底——你可以直接在 REPL 里查看当前模板对象的所有属性，调用它的方法，实时改动后立刻重新生成页面，完全不需要重启任何东西。

其次，Common Lisp 的宏系统让 Caveman 的源码变得极其简洁。整个项目大概只有几千行代码，却能完成核心的模板渲染和文件拷贝工作。这不是因为作者偷工减料，而是因为 Lisp 的表达能力确实强。

不过我必须坦诚地讲，如果你完全没接触过 Lisp，用 Caveman 需要先跨过一条学习曲线。你至少要会用 Quicklisp 安装依赖，会写最基本的 Lisp 表达式，能看懂 REPL 里的错误信息。好在 Caveman 的文档几乎是这个生态里写得最清晰的，配合我这篇文章里的步骤，普通人应该能在半天内搞定。

1.3 与传统静态生成器的核心差异对比

为了把 Caveman 的情况说清楚，我直接列一个对比表，方便大家理解它的取舍。

看这个表，Caveman 好像处处在“做减法”。但我用下来的体会是，这些减法在长期维护中变成了优势。因为没有配置文件，所以你永远不会遇到“配置项太多不知道改哪个”的纠结；因为没有模板语言，所以你写的 HTML 就是最终交付的 HTML，不存在模板渲染带来的意外样式；因为元数据是独立文件，所以你可以在任何文本编辑器里自由编辑，不像 frontmatter 那样必须遵守严格的格式。

2. 核心细节解析与实操要点

2.1 数据模型：页面、模板与 .meta 文件的三角关系

Caveman 的数据模型可以用一句话概括：一个 content 目录，里面放着你的原始模板；一个 output 目录，里面放着生成的成品；一个 .meta 文件，负责把“内容数据”注入到模板里。

理解这三者的关系是关键。我们拿一个最简单的例子说。假设你的 content 目录下有一个about.html，内容是这样的：

<html> <head><title>${title}</title></head> <body> <h1>${heading}</h1> ${content} </body> </html>

这个文件本身不是最终页面，它是一个模板。Caveman 在构建时会读取它，找出所有${变量名}格式的字符串，然后在同目录下的about.html.meta文件里查找对应的值，用真实内容替换掉这些字符串。替换完成后，结果写到 output/about.html，这才是浏览器能直接访问的页面。

那 .meta 文件长什么样？其实就是一个极简的文本文件，内容用变量名: 值的格式书写：

title: 关于我 heading: 一个爱折腾的博主 content: 这里是关于页面的正文内容，可以写得很长很长，换行也直接写就行。

Caveman 处理 .meta 文件的逻辑很朴素：按行读取，遇到第一个冒号就切分，左边当变量名，右边当值。变量名的命名规则遵循 Lisp 习惯，但严格来说你用什么字符都行，只要你能在模板里对应上。如果某个模板里引用了变量但 .meta 文件里没有定义，Caveman 不会报错，而是把整段${变量名}原样保留在输出文件里。这个行为有时候是坑，但有时候也是特色——你可以故意留一个未定义变量，等后续脚本去处理。

2.2 模板渲染机制的“没有机制”

Caveman 最让我佩服的设计，就是它的模板渲染机制其实“没有机制”。它没有像 Jinja2 或者 Liquid 那样的循环、条件、过滤器，就是纯字符串替换。

这听起来像是上古时代的工作方式，但实际用起来，反而给我一种很安心的感觉。

你想循环输出五篇文章？在 Jinja2 里你得写for循环，还要小心控制缩进。在 Caveman 里，你直接生成五段 HTML 复制粘贴到模板里就行。你想让某段内容只在特定页面显示？Jinja2 里有if语句，Caveman 里你就需要生成五个不同版本的页面模板。想动态计算？

听上去是不是很原始？但请仔细想想：你的博客真的需要这层动态模板能力吗？如果文章列表每次新增一篇文章只有一处变化，那你在模板文件里粘贴一个新链接，和让框架自动重新渲染，体验差别并不大。区别只在于：框架的做法可能在某个版本升级后改变列表排序规则，而手写链接永远不会变。

我自己做了个实验：用 Hugo 建一个十篇文章的博客，同时用 Caveman 建同样结构的站。一个月后，Hugo 那边我花了整整一个下午解决主题依赖更新导致的样式冲突，而 Caveman 这边我只需要记得添加文件、粘贴列表。这种“手动操作”的朴素，在长期运行中是极佳的抗熵武器。

2.3 元数据文件的灵活用法：不止是页面标题

Caveman 的 .meta 文件虽然格式简单，但玩法可以很丰富。除了常见的 title、description，你完全可以根据自己站点需求设计一套元数据体系。

比如我现在的博客源码目录下，每篇文章都会有一个 .meta 文件，里面不只是文章标题，还存了发布时间、文章摘要、标签列表。虽然 Caveman 没有内置标签云功能，我自己的发布脚本会在构建阶段读这些 .meta 文件，自动生成 tags 索引页面。这一步完全是在 Common Lisp 里写的循环代码，把目录下所有 .meta 文件读进来、拉出标签字段、输出一个带链接的 HTML 列表。

你甚至可以利用 .meta 文件实现简单的“分页文章”效果。比如一篇长教程需要分四页展示，只要分别写part1.html、part2.html、对应四个 .meta 文件，再在每页底部用相对路径链接到下一页。Caveman 对文件命名没有强制约定，所以你完全可以按自己的节奏组织。

但这里有一个我想提醒的坑：Caveman 的 .meta 文件名必须和模板文件名完全对应，且扩展名要拼接。假设模板叫post.html，元数据就得叫post.html.meta，不能写成post.meta。构建时 Caveman 会扫描所有 .html 文件，然后去同目录找 .html.meta，如果你文件缺失，它不会报错，只是原样输出模板，这时候页面就会出现一堆${}变量名。这个行为容易让人误以为模板语法写错了，其实是元数据文件没配对。

3. 实操过程与核心环节实现

3.1 环境搭建：从零开始装 Common Lisp 环境

既然 Caveman 是 Common Lisp 写的，第一步自然是装 Lisp 环境。这里我强烈推荐使用 SBCL（Steel Bank Common Lisp），它是目前最活跃、性能最好的实现之一，在各大 Linux 发行版和 macOS 上都有现成包。

在 Ubuntu/Debian 上，一行命令搞定：

sudo apt install sbcl

macOS 上如果你的 Homebrew 配置好了，也是毫不费劲：

brew install sbcl

装完 SBCL 之后，检查一下版本，确认能进入 REPL：

sbcl --version

输出类似SBCL 2.3.11就算成功。这时候你运行sbcl会进入交互环境，能输入 Lisp 表达式。先不用着急退出，我们要在这里装 Quicklisp。

Quicklisp 是 Common Lisp 世界的包管理器，类似 Python 的 pip。安装它的标准方式是在官网下载一个lisp-oriental.txt种子文件，然后用几条 Lisp 指令加载：

(load "quicklisp.lisp") (quicklisp-quickstart:install) (ql:add-to-init-file)

如果网速正常，这几行会下载 Quicklisp 的基础库，并将启动配置写入你的~/.sbclrc。以后每次打开 SBCL，都可以直接使用ql:quickload命令安装依赖。

装完 Quicklisp，就可以安装 Caveman 了。打开 SBCL，输入：

(ql:quickload :caveman)

它会自动下载和编译所有依赖，通常需要几分钟时间。如果前面步骤都没问题，这里会输出一堆编译信息，最后回到提示符，表示安装成功。走到这一步，你的环境就齐了。

注意：SBCL 在首次编译 Caveman 依赖时可能会报一些警告，比如WARNING: redefining之类的，这些在我多次尝试中基本都是无害的，可以忽略。真正要关注的是有没有ERROR字样，那才需要排查。

3.2 创建第一个页面的完整流程

装好环境后，我们来实战建站。Caveman 整体部署非常简单：本质上就是把源码下载到本地，然后在源码目录里写你的内容和模板。

你先自建一个工作目录，比如~/my-caveman-site/，里面需要有两个东西：content/目录和output/目录。前者放你的模板和源文件，后者放生成结果。还需要一个构建脚本，我习惯把它命名为build.lisp，内容是一个加载 Caveman 并调用构建函数的 Lisp 脚本。

这个构建脚本非常短，核心就三行逻辑：

(ql:quickload :caveman) (caveman:build :input #P"./content/" :output #P"./output/")

把这两行存成build.lisp，然后回到 shell 里执行：

sbcl --load build.lisp

SBCL 会加载 Quicklisp、加载 Caveman、执行构建、然后退出。整个过程几乎瞬间完成，连铜版纸印刷一个页面的工夫都不到。

3.3 实际生成一个带样式的最小站点

现在我们来做一个真正能看的页面。在 content 目录里创建index.html，内容写全：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>${title}</title> <style> body { font-family: sans-serif; max-width: 40em; margin: 3em auto; line-height: 1.7; } h1 { color: #333; } </style> </head> <body> <h1>${heading}</h1> <p>${intro}</p> <section>${content}</section> </body> </html>

然后同目录下创建index.html.meta：

title: 首页 heading: 欢迎来到我的穴居空间 intro: 这里是我用 Caveman 搭的完全手动站点。 content: 没有框架，没有主题，写什么就是什么。

运行sbcl --load build.lisp之后，去 output 目录看index.html，你会发现所有${变量名}都被替换成了对应文字。一个没有任何 JavaScript 依赖、没有构建缓存、直接了当的页面就完成了。

如果你像我一样喜欢写长文，可以按之前的 .meta 模式扩展多页面。我的习惯是 content 目录下维护几个子目录，比如pages/放静态页面，posts/放文章，每篇一个 HTML 模板加一个 .meta 文件。Caveman 对子目录的处理是透明的：它递归复制所有子目录结构到 output，所以你完全可以根据自己的心智模型来安排目录。

3.4 发布流程：用 rsync 同步到服务器

静态站点最爽的地方就是部署简单。生成完 output 目录后，任意静态托管都能直接使用。我自己一直用 rsync 同步到一台小服务器，命令极其简单：

rsync -avz --delete output/ user@example.com:/var/www/mysite/

这条命令会将本地 output 目录的内容全部推到服务器指定目录，--delete的作用是删除服务器上有而本地没有的旧文件，保证两端完全一致。对于没有后端的纯静态站，这就是完整的发布流程了。

如果你想进一步自动化，可以把这个 rsync 命令写进一个 makefile 或 shell 脚本，甚至放进 CI 里。但我个人建议最初阶段不要急着自动化——先手动跑了几十遍流程，理解每个环节在做什么，之后再接自动化，灵感才不会冲突。

4. 常见问题与排查技巧实录

4.1 SBCL 环境相关的各类报错

症状一：执行(ql:quickload :caveman)时报Unable to load Quicklisp。

这个基本都是 Quicklisp 没有正确安装。排查方法很简单：打开 SBCL 后先输入(ql:quickload :cl-ppcre)试试，如果连这个都报错，说明 Quicklisp 环境彻底没配好，重新跑一遍安装流程，确保(ql:add-to-init-file)执行成功。

症状二：编译过程中卡住，长时间没有输出。

我遇到过一次，原因是网络问题导致 Quicklisp 下载依赖特别慢。解决办法是换一个时间段，或者手动下载对应库放到本地目录，用(ql:quickload :caveman :local-path)之类的参数指定本地缓存目录。不过绝大多数情况下，耐心等一等都能正常完成。

症状三：启动 SBCL 时报package ... not found。

这多半是你之前安装过一次 Quicklisp 但后续手动删改了系统文件。最简单的处理是重开一个终端，或者彻底卸载 SBCL 重新来。反正 Lisp 环境本身就是可重复构建的，重来一次的成本很低。

4.2 构建后页面出现未替换的变量

这是我最早期踩到过的坑。你辛辛苦苦写好了模板，构建也成功了，打开输出文件一看，里面赫然躺着${title}这种原样字符串。

第一个排查点：检查同目录下是否有.meta文件，且文件名完全对应。比如模板是index.html，元数据就必须是index.html.meta。如果少个.meta后缀，Caveman 不会给你任何提示，直接原样拷贝。

第二个排查点：检查.meta文件里的变量格式。Caveman 的识别其实相对宽松，但如果你在.meta里用了中文冒号：而不是英文冒号:，整行识别就会失败。我的建议是所有元数据统一用英文标点，不要混用。

第三个排查点：模板里变量的写法。Caveman 用的是${变量名}，注意中间的变量名不要带空格。比如${ title }这种写法，解析器可能会匹配失败。保持紧凑，别敲空格。

4.3 HTML 特殊字符的转义问题

因为 Caveman 不做 Markdown 渲染，你的正文内容里所有 HTML 都是真实 HTML。这意味着如果你想展示<html>这样的代码片段，必须手动把<写成<，否则浏览器会把它当成标签解析。

这个体验相比 Markdown 来说确实麻烦一些。我的解决方案是：正文里放最小化的 HTML 标记，代码片段统一用<pre>包裹，并手动转义尖括号。对于大段代码展示的要求，可以通过一句简单的 Lisp 函数在构建时自动转义，也可以在我的发行脚本里用一个替换函数，将所有<和>替换为实体字符。写一次之后长期受益，不算太痛苦。

4.4 构建速度与文件数量的关系

顺着思路，很多人会担心：Caveman 这种“纯手工”的方式，文件多了会不会变慢？

我实测过一篇一百页的全静态站，Caveman 构建一次大约耗时不到一秒。因为它本质上只是文件拷贝加字符串替换，复杂度是 O(n)，而且每次构建都从零开始，不需要增量计算，反而少了很多缓存判断的开销。

不过如果你网站有个很大的图片目录，Caveman 也会原样复制这些图片文件到 output。因为缺乏文件监听机制，每次构建都会全量拷贝，这时候可能比 Hugo 的增量构建慢。我的解决办法是：content 目录下不放图片，所有大文件用外部 CDN 或单独命令批处理，构建脚本只负责 HTML 文件的生成。

4.5 快速排查清单

5. 工具选型与周边生态搭配

5.1 Caveman 适合与什么工具搭配使用

因为 Caveman 本身只是一个“把模板变成页面”的引擎，周边阵地就需要你自行搭建。我用下来感觉最顺手的搭配是：

• 编辑器：最普通的 VS Code，或者 Vim。因为无非是写 HTML 和纯文本，对编辑器没有任何特殊要求。
• 图片处理：用rsync同步的图片目录，配合cwebp或jpegoptim压缩脚本自动压缩后放到 content 下的assets目录。
• 内容组织：用一个简单的 shell 脚本模板，每次新文章时自动生成.html和.html.meta两个空文件，省去手敲相同框架的时间。

这个组合几乎没有跨语言协作的负担。没有 Node 模块，没有 Gem 依赖，所有文件都是普通文本或图片，备份和迁移极其简单。

5.2 为什么我不建议给它配太多插件

Caveman 有极简 API，理论上你可以在构建过程里挂很多预设操作。但我真心不建议一开始就做这一切。原因很简单：给 Caveman 做插件的思路，最后可能会让你重新发明一套复杂的模板系统，那就违背了用它做减法的初衷。

搭建过程中，遇到“这个功能 Caveman 没有支持”，我强烈建议大家先停下来想一想：这个功能真的需要吗？没有标签分类页，读者真就找不到你的文章吗？没有自动 RSS 生成，真的没有人订阅吗？很多功能在新站早期都是伪需求。等项目活跃程度上来、内容多到真的需要一个索引页时，再用脚本去生成，反而会让设计更贴近实际需求。

5.3 与 GitHub Pages 或云桶的配合

我认识不少朋友把 Caveman 生成的 output 目录直接推到 GitHub Pages 仓库里当静态站。这完全没有问题，因为 Caveman 输出的就是标准 HTML/CSS/JS，任何静态托管服务都能直接读懂。

我自己更常用的是 rsync 到 VPS。如果你希望免费托管，也可以用 S3 兼容的云存储，配合s3cmd sync把 output 目录同步上去。由于 output 每次构建都会重新生成所有文件，所以同步方案选最简单的全量同步就可以，不需要额外做增量计算。

慎用 CDN 缓存并必须保证同名文件更新后能刷新回源。每次构建后文件内容变化但文件名不变，CDN 如果缓存未过期，访客可能看到旧页面。解决办法是在构建时给 output 目录整体加一个版本号前缀，或者发布后手动刷新 CDN 缓存。

6. 独特心得：在“原始”与“高效”之间找平衡

用 Caveman 维护网站走到今天，我的心态经历了很大的变化。最开始觉得它简陋到可笑，慢慢地觉得它可靠到可爱。

这个“可靠”的感觉是有具体来源的。因为构建过程完全透明，我知道每一个字节的来源；因为没有任何包依赖在运行时出幺蛾子，我不需要半夜三更起来处理依赖升级冲突；因为目录结构完全自洽，我可以几年不碰构建脚本也不会遗忘它的逻辑。对一个内容创作者来说，这些“确定性”的成本远比那点构建速度和管理便利性重要得多。

当然，Caveman 不是万能钥匙。如果你要做的站点需要几十个页面、频繁更新的布局、团队协作，它那套手写所有列表链接的做法确实会拖后腿。这时候请老老实实去用 Hugo 或 Astro 这类现代工具，它们的设计就是面向这种复杂度的。工具的取舍没有对错，只有适合。

我个人在实际操作中最喜欢的画面，是每次写完一篇新文章后，打开一个编辑器窗口，创建.html和.html.meta两个文件，填好标题和正文，然后运行构建、同步、刷新浏览器。整个过程就是字面意义上的一趟“洞穴之旅”：把脑子里糊成一团的想法，变成服务器上一个干干净净的 HTML 文件，世界只有这一步之遥。

如果你被各种现代构建工具折腾得心浮气躁，不妨也试试这个 1984 年风格的清晨散步。它不会让你失望，也绝对会让你长出一些新的骨头。