这个名字我第一眼看到就乐了——caveman原始人。在博客生成器满天飞的今天居然有人给自己的项目起这么个返祖的名字。结果用下来我发现这名字起得非常诚实它确实是个“原始人”级别的工具不整花活、不堆依赖、没有复杂配置一条命令就能把 Markdown 变成整站静态页面。这篇文章就把这个叫 Caveman 的极简静态博客生成器完完整整拆给你看。它是谁、为什么值得用、怎么从零搭建、常见的坑有哪些全部用我实际折腾过的经验说话。如果你正好在找一个“写完 Markdown 直接发”的轻量博客方案或者你受够了 Hexo、Hugo 那一大堆配置和 Node/Go 环境依赖这篇文章应该能帮你省下不少时间。1. 项目拆解Caveman 的极简哲学与技术选型1.1 为什么叫“原始人”克制到极致的静态博客方案Caveman 是一个用 Rust 编写的静态博客生成器跟 Jekyll、Hexo、Hugo 属于同一类工具但它的设计立场跟那几个主流选手完全不一样。其他生成器追求的是“万能”主题市场几千套、插件生态几百个、配置文件洋洋洒洒能写上百行。而 Caveman 的核心理念就一个词返璞归真。作者把博客系统最核心的链路——Markdown 解析、模板渲染、静态文件输出——做扎实其余功能一个都不多给。实际使用中你会发现这种克制的设计反而让人轻松。我不需要记住十几条命令不需要维护插件列表不需要担心版本升级后某个主题模板不兼容。整个项目就一个二进制文件加一个放文章和模板的目录运行起来没有任何花哨的仪式感。你的精力可以100%放在写文章上而不是伺候工具。1.2 为什么技术选型选了 Rust而不是 Node 或 Python作为一个折腾过 Hexo 也试过 Pelican 的人我太清楚“生成器依赖地狱”是什么滋味了。Hexo 是基于 Node 的你得装 Node、装 npm、然后一个npm install下去装几百个包任何一个包版本冲突都会让你生不如死。Pelican 基于 Python虽然好一点但虚拟环境、pip 依赖同样是绕不开的坎。Caveman 用 Rust 的好处非常实在单文件分发编译完就是一个独立的可执行文件拷到任何 Linux/macOS 机器上直接能跑不需要目标机器上有 Rust 环境、不需要装运行时、不需要配置 PATH 以外的任何东西。这一点太像“原始人扛着一根木棒走天下”了工具就是工具不带累赘。构建速度极快Rust 编译出来的程序在处理文本渲染这类 IO 密集任务时速度表现非常恐怖。一个几百篇文章的博客构建时间也就是眨眼的工夫。内存占用小跑在低配服务器或者老笔记本上毫无压力不像某些 Electron/Node 系工具动辄吃掉几百兆内存。另外Rust 的静态类型系统让程序天生很稳。生成博客时最怕的就是某个模板变量拼错了运行时才发现。Caveman 在编译期就把很多错误挡住了这种确定性对写博客这种“低频但要求可靠”的场景来说非常加分。1.3 和主流静态站点生成器的横向对比如果你还没确定要不要选 Caveman我列个表给你参考。我不吹不黑只讲实际感受对比维度CavemanHexoHugoJekyll开发语言RustNode.jsGoRuby安装复杂度极低单二进制或 cargo 装中等需要 Node/npm低单二进制较高需要 Ruby 环境构建速度极快中等极快较慢文章多时明显配置复杂度极简几个字段中等模块较多中高很多人被 config 折磨中等主题生态小需自己动手庞大庞大庞大模板学习成本低类 Jinja 语法中需要用 EJS/Swig中高低适合场景追求极简、爱折腾、文章量不大的个人博客习惯 Node 生态的人复杂站点、文档站Ruby 用户或 GitHub Pages 默认说白了Caveman 的目标用户画像很清晰有一定动手能力、不需要海量主题、希望工具消失在内容背后的人。如果你需要的是一个开箱即用的炫酷大站那还是去用 Hugo 加现成主题。但如果你像我一样只是想安安静静写东西Caveman 会是让你上瘾的选择。2. 核心功能与运行原理拆解2.1 一条数据流水线从 Markdown 到静态 HTMLCaveman 的工作流程不复杂理解它对你后面排错特别有帮助。整个处理流程是典型的单向数据流启动后程序先读取站点配置文件拿到站点标题、URL、主题路径这些全局信息然后扫描content目录下的 Markdown 文件逐个解析文件头部的参数块标题、日期、标签等和正文内容解析完成之后把所有文章按时间倒序排好丢给对应的模板进行渲染最后把渲染好的 HTML 文件和静态资源一起写入public目录。这个流水线几乎是所有静态站点生成器的通用模型但 Caveman 的执行特别直接。它没有增量构建、没有内容管道插件机制、没有资源处理链就是“扫一遍、渲一遍、输出一遍”。这种简单带来的好处是行为可预测。你永远不会遇到那种“源码没变但构建结果莫名其妙不同”的玄学问题。2.2 配置文件的几个关键参数别乱填Caveman 的配置文件是 TOML 格式文件内容非常精简。我自己的站点配置文件长这样site_name 荒野笔记 base_url https://myblog.example.com description 写代码也写生活 theme default content_dir content output_dir public syntax_highlight true这里面对生成结果影响最大的也是最容易出问题的是base_url。base_url决定了两件事一是 RSS 和 sitemap 里出现的站点绝对链接二是页面里资源引用时的绝对路径计算。如果你提前用base_url生成了页面后来换了域名光改配置再重新构建是不够的因为已经写进 HTML 里的链接还是旧域名。我的经验是域名一旦定好就别频繁改。实在要改务必重新构建后全站检查一遍页面源码里的资源路径。syntax_highlight控制代码高亮默认用类似 highlight.js 的前端方案。如果你的博客基本不贴代码可以直接关掉构建产物体积会小不少。2.3 文章前面的参数块决定了文章能不能被正确识别Caveman 解析文章时依赖 Markdown 文件开头的一段元信息。如果你用惯了 Hexo 或 Hugo这个格式你会很熟悉--- title: 我的第一篇 Caveman 博客 date: 2025-01-15 10:30:00 tags: [随笔, Rust] draft: false --- 这里是正文内容……有几个坑我帮你提前踩平了date格式最好写标准时间格式比如2025-01-15 10:30:00如果你后面要生成 RSS这个字段会被严格校验格式不对会直接报错或者生成一个不合法的时间。draft字段标识草稿文章。我强烈建议所有文章默认带这个字段平时写半截就先标成true构建时它会自动被跳过不会污染线上站点。等我彻底写完再改成false重新构建发布。slug字段控制文章链接路径。这个字段重点说一下Caveman 默认会用文件名作为 URL 的一部分如果你的文件名是中文或者带着空格、特殊符号生成的链接会很丑而且部分服务器解析会有问题。我会在每篇文章里手动指定一个简短英文别名比如这篇hello-caveman.md对应slug: hello-caveman发布后链接就是/post/hello-caveman/干净利落。2.4 模板系统的套路看懂这三点改主题不求人Caveman 用的是类 Tera 的模板引擎语法上跟 Jinja2 很像。你不需要成为模板开发专家只需要知道三个最核心的套路就能随意改造主题第一个是变量输出。想显示标题或站点名字直接在模板里写h1{{ site.site_name }}/h1第二个是循环遍历。首页要列文章列表就用{% for post in posts %} a href{{ post.url }}{{ post.title }}/a span{{ post.date }}/span {% endfor %}第三个是条件判断。比如没有文章时显示提示语可以这样{% if posts %} ...列表输出... {% else %} p还没有文章/p {% endif %}掌握了这三点首页、列表页、文章页、存档页、标签页的基本逻辑你都能看懂了。Caveman 的默认主题就是一堆非常朴素的 HTML 模板你把默认主题拷贝出来改一改就是完美的新主题。这一部分动手的乐趣比用现成主题大得多毕竟整个站点的样式都由你自己掌控。3. 实操记录从零搭一个 Caveman 博客并发布上线3.1 安装 Caveman两种方式任选一种安装这一步非常简单比配 Node 环境省心一百倍。方式一直接从 GitHub Releases 下载对应平台的预编译二进制文件。下载完解压把它放到/usr/local/bin或任意已经在PATH里的目录执行caveman --version能正常输出版本号就装好了。方式二如果你本机有 Rust 工具链用cargo安装也可以cargo install caveman这条命令会自动下载源码并编译安装最终效果一样。我个人推荐方式一速度快如果你后面想改 Caveman 源码那就用方式二。3.2 初始化站点目录三秒钟得到一个可运行骨架安装完了找个工作目录开始干活caveman init myblog cd myblog执行完init之后目录结构大概长这样myblog/ ├── config.toml # 站点配置文件 ├── content/ # 放 Markdown 文章 │ └── post/ └── themes/ └── default/ # 默认主题目录 ├── templates/ └── static/如果你init之后发现themes目录是空的也不慌从 GitHub 仓库里把默认主题拷进去或者先随便写一个最简单的模板就行。后面我会讲怎么快速做一个够用的模板。3.3 改配置、写文章、本地预览三步走先把config.toml里的站点信息改成自己的这一步别偷懒特别是base_url我前面已经说过它的重要性。然后在content/post下新建一篇 Markdown。记得带上参数块标题、日期、标签都写好。比如--- title: 你好Caveman date: 2025-02-10 20:00:00 tags: [随笔] slug: hello-caveman --- 今天开始用 Caveman 写博客。接下来在项目根目录执行caveman build构建完成后public目录下会出现整套站点文件。想本地预览运行caveman serve然后浏览器打开http://localhost:8080具体端口按终端提示为准就能看到你的博客了。这个预览环节是我个人使用频率最高的命令。我每次写文章都会先build再serve检查确认排版没问题、标签链接能点、时间显示对了再进入发布流程。别偷懒本地预览这道工序能拦截绝大多数低级失误。3.4 部署发布静态文件丢到任意托管就行Caveman 的产物就是一组纯静态的 HTML、CSS、JS 和图片资源完全没有后端依赖。所以部署方式极其自由放到 GitHub Pages 的仓库里用 Pages 服务托管扔到任意 VPS 上用 Nginx 托管传到对象存储开静态网站托管或者放到公司内网服务器上只要是个 Web 服务器就能跑。我自己的流程是写了一个deploy.sh脚本内容很简单#!/bin/bash caveman build rsync -avz --delete public/ usermy-server:/var/www/myblog/执行bash deploy.sh一条命令完成构建加部署。这里特别提醒一下--delete参数它会删除服务器上目标目录里多余的文件保证线上就是本地真实情况的镜像。但如果你的服务器上还放了其他东西千万别乱加--delete否则会误删文件。3.5 动手做一个炸开源码的极简主题默认主题虽然能用但九成的人都会想换掉。我的建议是直接拷贝默认主题作为起点改完拷贝另存为新名字。比如把themes/default复制成themes/mytheme然后在config.toml中把theme default改成theme mytheme。之后你就可以放心大胆地改模板和样式了改乱了随时切回默认主题不用重装。一个最简单的首页模板看起来像这样!DOCTYPE html html langzh-CN head meta charsetutf-8 meta nameviewport contentwidthdevice-width, initial-scale1 title{{ site.site_name }}/title /head body h1{{ site.site_name }}/h1 p{{ site.description }}/p {% for post in posts %} article h2a href{{ post.url }}{{ post.title }}/a/h2 time{{ post.date }}/time /article {% endfor %} /body /html从这个模板起步你再加分类、加标签页、加页脚逐步就会积累出自己的专属主题。改模板唯一的硬要求就是变量名别写错。拿不准的字段去默认模板里查这是最可靠的参考。4. 常见问题与避坑技巧实录4.1 实战遇到的高频问题速查表在我用 Caveman 的这段时间里身边朋友跑来问的、以及我自己踩过的坑汇总成了一张表。你可以直接收藏遇到问题对照着看问题现象原因分析解决方法文章生成但首页不显示文章date是未来时间或draft: true检查参数块里的日期和draft字段构建时报日期解析错误date格式不符合指定格式改成2025-02-10 20:00:00这种标准格式页面图片显示不出来图片路径用了绝对路径但base_url不对确认base_url和资源引用路径一致标签页是空的标签列表没有在模板里遍历在模板中添加标签的for循环中文文件名生成了奇怪 URL没有指定slug字段在文章参数块中手写一个英文slug重新部署后老链接失效文章slug变了slug一旦发布就别改要改就做跳转4.2 三个血泪教训希望你不用亲自踩第一个教训是备份内容比备份整个站更重要。我刚开始用的时候习惯把整个项目目录打包上传云端。后来有一次误删了content里的文章草稿虽然源码都还在但那些没写完的碎碎念全没了疼得我牙痒。后来学乖了用 Git 管理整个项目目录每次写完文章就提交一次。public这种构建产物目录加进.gitignore只做构建部署不做版本管理。第二个教训是别用发布时间做目录分类。一开始我为了“整洁”把文章按年份分目录比如content/post/2025/hello.md。结果后来发现迁移主题、批量修改路径时分类目录让所有操作都多绕了一圈。现在我就统一用content/post/一个文件夹标签系统已经足够做分类了简单就是高效。第三个教训是先预览后发布再检查。我犯过最离谱的一个错本地改了文章执行rsync部署的时候忘了先caveman build导致线上显示的还是旧版本。折腾了半天才发现问题不在服务器配置而是构建产物压根没更新。现在我部署脚本必须这样写#!/bin/bash caveman build rsync -avz --delete public/ my-server:/var/www/myblog/串起来之后只要构建失败部署就不会执行从根上杜绝了“把旧文件传上去”的风险。4.3 为什么我最终留在了 Caveman不仅仅是工具选择用了 Caveman 大半年我最大的感受不是“拿到了一个博客工具”而是“找回了写博客的初心”。用 Hexo 的时候我花了很多时间挑主题、翻插件、看配置文档真正写文章的时间反而被挤压。换了 Caveman 之后因为实在没什么好折腾的我只能老老实实打开编辑器写内容。这听起来有点反讽但它确确实实改善了我的创作频率。当然如果想追求极致的自动化Caveman 也能配合 GitHub Actions 做 CI/CD把构建和部署全部托管到云端实现“推送即发布”。但我个人还是偏爱本地构建完毕再上传的流程因为每一步自己都看得见、控制得住出了问题能立刻定位到是本地原因还是环境原因。最后分享一个我自己觉得最实用的习惯坚持在本地用caveman serve检查每一篇文章的最终表现不是看一眼就完事而是把首页、标签页、归档页、上下篇文章翻页都点一遍。静态站点生成器最尴尬的地方在于你永远不知道哪个模板少了数据会渲染成什么样。所以每次发布前的一遍手动“巡游”是成本最低、回报最稳的质量保障。这个工具的教育是生活和工作里很多工具其实都比我们想象的更简单。你需要的不是另一个更重的平台而是一根趁手、够硬的“木棒”。Caveman 之于博客就是这样一根木棒。