caveman 这个名字第一眼看到就让人想起原始人、石器时代直觉上就是个返璞归真的东西。最近在技术社区里翻到一个名为caveman的开源项目第一眼没太在意后来发现这个项目解决了我长期以来的一个大痛点写博客和做小站点时不想被复杂的框架、繁重的构建工具和各种依赖绑架。花了一晚上把它用起来之后我决定把这套体验完整地写下来。这篇文章不是官方文档而是我从零折腾一遍后的实操记录。我会把这个项目的核心设计、部署思路、常见坑位和场景扩展都拆开讲清楚。如果你也因为 Hexo、Hugo 这类工具里层层配置和依赖链感到厌烦想回到手写 Markdown一条命令出站的原始快感这篇东西应该能帮你省不少时间。对于完全零基础的人我也把基本概念用大白话解释了照着敲命令就能出效果。1. 项目定位与核心设计思路1.1 它到底是什么caveman 是一个极简的静态站点生成器核心功能就是把 Markdown 文件转换成可以直接托管到任意 Web 服务器上的纯静态页面。你可以把它理解为一个输入纯文本笔记输出整站 HTML的小作坊。和主流的 Hexo、Hugo 这类动辄带几十个依赖项的框架相比caveman 走的是完全相反的路线——少即是多。它的名字暗合了核心哲学像穴居人一样简单直接。不需要 Node 环境、不需要 Ruby、不需要 Python甚至不需要网络下载一堆依赖包。整个工具在本地编译成一个独立的可执行文件放到哪台机器都能跑。这对我这种经常换电脑、又不想每次在新环境里折腾环境变量的人来说简直是救命稻草。1.2 选这条路线背后的理由我之前用 WordPress 写过一段时间说实话被折腾得够呛。一个插件没升级就能把整个站搞宕机数据库还要定期备份安全补丁永远追不完。后来换到 Hexo清爽了一些但 Node 依赖动不动出现版本冲突npm install报错能刷一整屏而且每次想改个样式还得编译半天。caveman 把这些问题一次性解决了。它选择了一条反工具化的路线零依赖不需要安装任何运行时环境编译产物是一个原生二进制文件。你把它丢到服务器、Docker 容器或者任何一台 Linux 机器上直接运行即可。无构建步骤很多静态站生成器在开发阶段都要开一个热重载服务改个标点都能触发全量重新构建。caveman 的思路是写完跑一次完事就像你写了个脚本然后执行一样朴素。内容即文件你的所有内容就是文件夹里的.md文件没有数据库没有 API。迁移成本低到几乎可以忽略——把文件夹打个包搬到别处站就搬走了。1.3 它不适合谁任何工具都有边界。如果你需要在线编辑、多用户协作、动态评论区或者希望用可视化后台写文章那 caveman 不适合你。它适合的是像我这样内容为王、看重长期维护成本、喜欢用 Vim 写东西的人。用生活类比来说这就像是手工木工和全自动数控铣床的区别——一个是想要掌控每一个细节一个是追求批量产出。没有谁更高明只是路线不一样。2. 核心功能拆解与实现要点2.1 目录结构与文件路由caveman 的工作目录非常干净初次初始化的结构是这样的. ├── caveman.toml # 站点配置文件 ├── content/ # 存放所有 Markdown 文章 │ ├── _index.md # 首页内容 │ └── posts/ # 文章目录 │ └── hello-world.md ├── templates/ # HTML 模板文件 │ ├── base.html │ ├── index.html │ └── post.html └── public/ # 构建产物目录它设计的核心逻辑是目录即路由。你在content下面怎么放文件生成出来的 URL 就长什么样。posts/hello-world.md生成的就是/posts/hello-world.html。你不需要在文件头部写死permalink也不用在配置里设置route规则。这个概念我一开始觉得太简单后来用久了才意识到这个设计的高明之处——少了一层心智负担。2.2 文章元数据与 Front Matter每篇文章开头有一段 YAML 格式的元信息区块用来定义标题、日期、标签、分类等。比如--- title: caveman 完全上手指南 date: 2025-01-15 tags: [static-site, markdown] category: tech ---这里有个细节值得说明元数据是可选的。如果你只在文件第一行写个# 标题它也能正常渲染标题会直接从 H1 里自动提取。对随手写的场景非常友好——灵感来的时候你不用先填一堆表单写就完了晚了再补元数据也来得及。2.3 模板语法与变量caveman 的模板语法借鉴了 Go 生态的text/template风格但做了很多简化。一个最基本的文章模板长这样!DOCTYPE html html langzh-CN head title{{ .Title }}/title /head body article {{ .Content }} /article /body /html模板支持循环、条件判断和自定义变量。更关键的是可以用.Site.Title、.Site.Description这些全局变量以避免在每个页面里重复写死信息。对于具备基础 HTML 知识的人来说这套模板几乎没有学习成本它就是带几个小占位符的 HTML。我特意对比过其他框架的模板写法caveman 的思路是把最少必需暴露给你没有抽象封装成自定义 DSL也没有数据层与模板层的复杂绑定。很多同类工具花太多时间搞什么主题机制、skin 系统caveman 干脆让你直接改 HTML反而所有问题都一目了然。2.4 内置的本地开发服务器虽然它主打无构建但开发阶段还是内置了一个极简的 HTTP 服务。在项目目录下运行caveman server就能起一个本地预览服务默认端口是8080支持文件变化自动刷新。需要注意的是这个功能定位是够用就行它不会去做模块热替换、路由调试这类重型开发工具支持。也就是说复杂 SPA 项目或者需要服务端逻辑的场景它还真是无能为力但就预览纯静态站和写文章来说已经绰绰有余了。3. 从初始化到发布的完整实操记录3.1 初始化一个项目假设你已经下载好 caveman 的可执行文件别问我哪里下官方仓库 README 里给了三个主流系统的二进制包然后执行caveman init mysite cd mysite这一条命令会生成上面那个目录结构以及一份caveman.toml默认配置。打开配置文件先改几个关键字段title 我的极简博客 description 用 caveman 驱动的个人站点 author 张三 base_url https://example.com language zh-CN theme defaultbase_url这个字段我想单独提醒一下它决定了站内链接和sitemap.xml里 URL 的写法。如果你先在本地用http://localhost:8080测试后面发布到正式域名后忘了改那生成的所有绝对链接都会指向 localhost。前期不用纠结记住上线前检查一下就好。3.2 写第一篇文章并构建在content/posts/下建一个my-first-post.md文件caveman new post my-first-post这个命令会在content/posts/下生成一个带基础元数据的模板文件。不过说实话我用惯了以后都是自己手动建文件因为模板里的默认值我基本都会改。接下来用任意编辑器打开这个文件把内容填进去--- title: caveman 实操笔记 date: 2025-01-15 tags: [caveman, markdown] --- 这里是正文支持标准的 Markdown 语法。 ## 二级标题 - 列表项 - 列表项 **加粗**、*斜体*、行内代码都不在话下。保存后回到终端运行caveman build你会看到一条简短的输出大意是生成了多少页面耗时多少毫秒然后所有结果落在public/目录。整个过程干净利落没有铺天盖地的日志没有编译成功请继续观看下一集式的花哨反馈。3.3 部署到服务器或托管平台构建完成后public/里的内容就是你要发布的所有产物。你可以选择多种方式上线方式一传统服务器rsync -avz --delete public/ useryour-server:/var/www/html/方式二对象存储托管阿里云 OSS 或者腾讯云 COS 之类的服务都支持从文件夹批量上传。上传完成后往往还要配置一下静态网站托管开关然后在控制台里找到分配的访问地址填到base_url里再重新构建一次保证链接正确。方式三Docker 镜像部署caveman 的静态产物可以用官方 Nginx 镜像包一下Dockerfile 简单到离谱FROM nginx:alpine COPY public/ /usr/share/nginx/html构建镜像推到仓库再启动容器几秒钟的事。我个人偏好的组合是本地caveman build配合脚本一键rsync到一台最低配的云服务器。这套流程跑起来之后发布这个动作的心理门槛降低了很多不再像以前一样要考虑各种流程就是敲一个命令十秒钟全部搞定。3.4 关于性能的一些实测我建了一个包含 500 篇文章的测试仓库做压力测试构建耗时在 1.2 秒左右老式 Intel 笔记本上跑的。生成的页面文件都是纯 HTML没有内联脚本的阻塞也没有外链的 CDN 依赖用 Lighthouse 跑分各项分数的满分概率极高。凡是经历过首屏等三秒才能交互那种重前端站点的人回到这种传统多页静态站点时会有一种久违的轻快感。4. 实战中遇到的常见问题与排查技巧4.1 构建后页面打不开这个问题的出现频率最高十次里头九次是因为路径问题。caveman 生成的都是相对路径的吗不一定。如果你在模板里写死了/assets/style.css而站点被托管在子目录下比如https://blog.example.com/caveman/这种那访问路径就会错。排查思路是先在本地用caveman server起服务打开浏览器开发者工具看 Network 里资源请求路径和实际文件路径的对应关系。还有一点构建之前先把caveman.toml里的base_url临时改成http://localhost:8080确认一切正常再改回正式域名重新构建。这一类问题排查完了90% 的白屏问题都能被消灭。4.2 模板里的循环不生效caveman 的模板循环语法是这样的{{ range .Posts }} div classpost-item h2a href{{ .URL }}{{ .Title }}/a/h2 /div {{ end }}常见错误是只写了一半闭合标签。它毕竟是 Go 模板那套语法对标签闭合有严格的要求。还有个小细节range内部的变量作用域会被 . 替换为当前遍历项如果你在循环里想访问站点全局变量就得写$.Site.Title拿全局上下文这个$符号是新手最容易漏掉的。4.3 Markdown 渲染结果和预览不一样这个我来来回回踩了不下三次。主流编辑器的 Markdown 预览和 caveman 内置的渲染引擎对换行处理有差异。部分编辑器采用 GFMGitHub Flavored Markdown规则两个普通换行不会生成新段落而 caveman 的默认渲染器认为是段落分隔。解决办法很简单段落之间就老老实实敲两个换行别只打一个。还有表格语法记得表头和分隔行之间必须有一个空行这个规则严格执行起来会避免很多看起来没渲染对的麻烦。4.4 本地可以预览服务器上却 404如果确认public/目录上传完整但服务器上出现了 404先看一下 Nginx/Apache 的伪静态规则。caveman 生成的是.html文件如果服务器配置了去掉扩展名的重写规则反而会造成访问/posts/hello-world找不到文件。一个最简单的排查方法直接访问带.html后缀的完整路径试试如果带后缀能打开但不带后缀打不开那就说明重写规则有问题。要么在后缀为html时关闭重写要么改造 URL 结构别在这一块纠结太久。4.5 关于标签与分类的若干细节caveman 支持在文章 Front Matter 里写tags和category默认配置下它会为每个标签生成一个独立的归档页。但默认模板里并没有归档页的样式设计——这需要你自己写。如果你没精力做也可以直接不填标签让它退化为全部文章列表模式。有些人可能会被强大到可以自动整理分类的预设立场束缚其实轻量的归档页功能已经足够满足多数个人站点了。4.6 排查思路速查表下面是我在实际使用中总结的一个快速排查清单任何不正常的现象先按顺序自查大部分问题都能在这张表里解决症状检查顺序最可能的坑页面样式全丢1. 模板路径 2. base_url 3. 资源文件命名资源引用写死绝对路径文章列表为空1. Front Matter 格式 2. 文件后缀 3. 目录位置YAML 缩进用了 Tab构建报错1. 模板标签闭合 2. 配置文件语法 3. 版本更新说明模板里用了新版本才支持的函数中文乱码1. 文件编码 2. 模板声明 3. HTTP 头文件存成了 GBK应统一为 UTF-85. 场景扩展与组合玩法5.1 搭建个人知识库或笔记系统caveman 这种目录即文件的结构天然适合做知识库。我现在的做法是在content/下面建了多个子目录分别放工作笔记、读书摘录和随想构建完就能得到一个可离线浏览的知识站点。配合rsync自动同步到服务器后手机浏览器也能随时访问。我之前用 Notion 的时候最大的问题是排版时忍不住改样式而且数据导出格式非常混乱用 caveman 之后彻底没这个顾虑了因为根本没有任何花哨的排版功能。5.2 作为产品文档站产品文档通常不大但需要版本管理。caveman 和 Git 配合得非常完美Markdown 天然支持 diff模板是纯文本构建产物丢弃也无所谓。我在 GitHub 上维护一套文档项目每次发版就新建一个分支然后用 CI 在 GitHub Actions 里执行caveman build再推送产物到 Pages 服务整个过程不需要在本地装任何额外开发环境。5.3 与自动化脚本配合因为构建命令只有一个二进制文件想把这套东西放进任何自动化流水线里都极其容易。比如我写过一个监控脚本每天从数据库导出统计数据塞进content/reports/下生成 Markdown然后调用caveman build生成报告页面。这个过程中没有奇怪的中间层也没有另一个运行环境的瓶颈。对于轻量数据可视化的需求这是个很灵活的方案。5.4 改造模板主题caveman 没有官方的主题市场我的印象中甚至没有一个集中下载的地方但换个模板的成本低到完全可以手写。我从零开始写了一个类似新闻简报的模板总共也就花了两天时间而且其中一天还是在调 CSS 的移动端适配。与其找现成主题我更推荐直接基于默认模板改。这种造轮子的过程会让你对整个站点的每个像素都了如指掌。5.5 不用构建工具能不能直接搭配 Tailwind 之类能但我不建议。caveman 的哲学是少就是多如果你非要引入 PostCSS、Tailwind CLI 这一整套构建链等于把已经扔掉的复杂度又从后门捡了回来。我个人的取舍是极简风格就用纯手写 CSS。如果你一定要用 Tailwind也请用它的 CDN 版至少别给自己找编译的麻烦。这类选择直接决定项目的长期维护成本值得慎重考虑。6. 一些不得不说的局限与取舍6.1 不适合的类型没有四舍五入的万能工具caveman 的边界也很清楚。如果要做一个千人互动的社区、带用户系统的 Web 应用或者想用 Vue/React 做前后端分离的前台别选它。它就是个从 Markdown 到 HTML的翻译官多余的活干不了也不该让它干。有人可能会说可以配合 Ajax 实现交互呀但在单机文件环境里这类方案往往绕一圈回来复杂度全堆在自己身上得不偿失。6.2 多语言支持官方没有提供多语言网站的一键方案。我实测下来如果你的站点需要中英文双语版本需要自己规划目录结构比如content/zh/和content/en/再在模板里手动判断当前文章属于哪个目录。可以做但毫无捷径。如果是内容频繁更新的双语团队项目这个方案维护成本会逐渐偏高。6.3 搜索功能没有内置搜索。最粗糙但有效的做法是生成一个纯客户端搜索页面把所有文章的标题和正文塞进一个 JSON 文件前端拿 JS 做过滤。内容多了以后这种方式肯定有性能瓶颈但对于几千篇文章以内的小站体验完全够用。我在本地测试时使用这个方案配合一份简单索引搜索平均响应时间也就是几十毫秒量级。6.4 关于社区与生态说实话caveman 的社区生态和 Hugo/Hexo 完全不在一个量级上没有Plugins广场也没有Theme市场。但这恰恰可能是一种优势——你不需要卷进工具链的军备竞赛它的一切都很稳定。如果你在网上搜到的大部分是英文资料也符合情理极简方案在中文圈子里讨论得不多大家更喜欢功能全的全家桶。7. 我最后的几条实操心得写到这里其实已经把这套工具的核心都讲透了。再说几句我折腾这一两周的体感它最值钱的地方不是快而是不打扰。以前的工具总会用生命周期钩子、插件机制、提醒更新弹窗来占据你的注意力而 caveman 只是安静地把你写的 Markdown 变成网页你甚至会忘记它本身的存在。一个小技巧你可以在content/_index.md的 Front Matter 里设置一个template: custom字段为此页面指定一份独立的模板。这样首页想做一个完全不一样的排版时不会干扰文章模板的结构。这种平时用不到但关键时刻救命的细节最能反映设计者对开发者体验的理解。还有一个好习惯是把构建产物的public/目录加进.gitignore。既然它能随时从源文件重建就没有必要把生成物纳入版本控制。有人喜欢把产物也 Push 上去来免服务器构建那是另一个取舍但建议至少保持源目录的清爽。最后再分享一个关于要不要选它的判断标准问一下自己——如果你三个月后需要重新把这个站迁移到另一台机器上你愿意为此付出多少时间去回忆当初的环境配置如果答案是半小时以内搞定那就值得选。按这个标准caveman 毫无疑问是很合格的。工具是为人服务的能把为人服务这件事做干净就已经很难得了。
caveman 这个名字第一眼看到就让人想起原始人、石器时代直觉上就是个返璞归真的东西。最近在技术社区里翻到一个名为caveman的开源项目第一眼没太在意后来发现这个项目解决了我长期以来的一个大痛点写博客和做小站点时不想被复杂的框架、繁重的构建工具和各种依赖绑架。花了一晚上把它用起来之后我决定把这套体验完整地写下来。这篇文章不是官方文档而是我从零折腾一遍后的实操记录。我会把这个项目的核心设计、部署思路、常见坑位和场景扩展都拆开讲清楚。如果你也因为 Hexo、Hugo 这类工具里层层配置和依赖链感到厌烦想回到手写 Markdown一条命令出站的原始快感这篇东西应该能帮你省不少时间。对于完全零基础的人我也把基本概念用大白话解释了照着敲命令就能出效果。1. 项目定位与核心设计思路1.1 它到底是什么caveman 是一个极简的静态站点生成器核心功能就是把 Markdown 文件转换成可以直接托管到任意 Web 服务器上的纯静态页面。你可以把它理解为一个输入纯文本笔记输出整站 HTML的小作坊。和主流的 Hexo、Hugo 这类动辄带几十个依赖项的框架相比caveman 走的是完全相反的路线——少即是多。它的名字暗合了核心哲学像穴居人一样简单直接。不需要 Node 环境、不需要 Ruby、不需要 Python甚至不需要网络下载一堆依赖包。整个工具在本地编译成一个独立的可执行文件放到哪台机器都能跑。这对我这种经常换电脑、又不想每次在新环境里折腾环境变量的人来说简直是救命稻草。1.2 选这条路线背后的理由我之前用 WordPress 写过一段时间说实话被折腾得够呛。一个插件没升级就能把整个站搞宕机数据库还要定期备份安全补丁永远追不完。后来换到 Hexo清爽了一些但 Node 依赖动不动出现版本冲突npm install报错能刷一整屏而且每次想改个样式还得编译半天。caveman 把这些问题一次性解决了。它选择了一条反工具化的路线零依赖不需要安装任何运行时环境编译产物是一个原生二进制文件。你把它丢到服务器、Docker 容器或者任何一台 Linux 机器上直接运行即可。无构建步骤很多静态站生成器在开发阶段都要开一个热重载服务改个标点都能触发全量重新构建。caveman 的思路是写完跑一次完事就像你写了个脚本然后执行一样朴素。内容即文件你的所有内容就是文件夹里的.md文件没有数据库没有 API。迁移成本低到几乎可以忽略——把文件夹打个包搬到别处站就搬走了。1.3 它不适合谁任何工具都有边界。如果你需要在线编辑、多用户协作、动态评论区或者希望用可视化后台写文章那 caveman 不适合你。它适合的是像我这样内容为王、看重长期维护成本、喜欢用 Vim 写东西的人。用生活类比来说这就像是手工木工和全自动数控铣床的区别——一个是想要掌控每一个细节一个是追求批量产出。没有谁更高明只是路线不一样。2. 核心功能拆解与实现要点2.1 目录结构与文件路由caveman 的工作目录非常干净初次初始化的结构是这样的. ├── caveman.toml # 站点配置文件 ├── content/ # 存放所有 Markdown 文章 │ ├── _index.md # 首页内容 │ └── posts/ # 文章目录 │ └── hello-world.md ├── templates/ # HTML 模板文件 │ ├── base.html │ ├── index.html │ └── post.html └── public/ # 构建产物目录它设计的核心逻辑是目录即路由。你在content下面怎么放文件生成出来的 URL 就长什么样。posts/hello-world.md生成的就是/posts/hello-world.html。你不需要在文件头部写死permalink也不用在配置里设置route规则。这个概念我一开始觉得太简单后来用久了才意识到这个设计的高明之处——少了一层心智负担。2.2 文章元数据与 Front Matter每篇文章开头有一段 YAML 格式的元信息区块用来定义标题、日期、标签、分类等。比如--- title: caveman 完全上手指南 date: 2025-01-15 tags: [static-site, markdown] category: tech ---这里有个细节值得说明元数据是可选的。如果你只在文件第一行写个# 标题它也能正常渲染标题会直接从 H1 里自动提取。对随手写的场景非常友好——灵感来的时候你不用先填一堆表单写就完了晚了再补元数据也来得及。2.3 模板语法与变量caveman 的模板语法借鉴了 Go 生态的text/template风格但做了很多简化。一个最基本的文章模板长这样!DOCTYPE html html langzh-CN head title{{ .Title }}/title /head body article {{ .Content }} /article /body /html模板支持循环、条件判断和自定义变量。更关键的是可以用.Site.Title、.Site.Description这些全局变量以避免在每个页面里重复写死信息。对于具备基础 HTML 知识的人来说这套模板几乎没有学习成本它就是带几个小占位符的 HTML。我特意对比过其他框架的模板写法caveman 的思路是把最少必需暴露给你没有抽象封装成自定义 DSL也没有数据层与模板层的复杂绑定。很多同类工具花太多时间搞什么主题机制、skin 系统caveman 干脆让你直接改 HTML反而所有问题都一目了然。2.4 内置的本地开发服务器虽然它主打无构建但开发阶段还是内置了一个极简的 HTTP 服务。在项目目录下运行caveman server就能起一个本地预览服务默认端口是8080支持文件变化自动刷新。需要注意的是这个功能定位是够用就行它不会去做模块热替换、路由调试这类重型开发工具支持。也就是说复杂 SPA 项目或者需要服务端逻辑的场景它还真是无能为力但就预览纯静态站和写文章来说已经绰绰有余了。3. 从初始化到发布的完整实操记录3.1 初始化一个项目假设你已经下载好 caveman 的可执行文件别问我哪里下官方仓库 README 里给了三个主流系统的二进制包然后执行caveman init mysite cd mysite这一条命令会生成上面那个目录结构以及一份caveman.toml默认配置。打开配置文件先改几个关键字段title 我的极简博客 description 用 caveman 驱动的个人站点 author 张三 base_url https://example.com language zh-CN theme defaultbase_url这个字段我想单独提醒一下它决定了站内链接和sitemap.xml里 URL 的写法。如果你先在本地用http://localhost:8080测试后面发布到正式域名后忘了改那生成的所有绝对链接都会指向 localhost。前期不用纠结记住上线前检查一下就好。3.2 写第一篇文章并构建在content/posts/下建一个my-first-post.md文件caveman new post my-first-post这个命令会在content/posts/下生成一个带基础元数据的模板文件。不过说实话我用惯了以后都是自己手动建文件因为模板里的默认值我基本都会改。接下来用任意编辑器打开这个文件把内容填进去--- title: caveman 实操笔记 date: 2025-01-15 tags: [caveman, markdown] --- 这里是正文支持标准的 Markdown 语法。 ## 二级标题 - 列表项 - 列表项 **加粗**、*斜体*、行内代码都不在话下。保存后回到终端运行caveman build你会看到一条简短的输出大意是生成了多少页面耗时多少毫秒然后所有结果落在public/目录。整个过程干净利落没有铺天盖地的日志没有编译成功请继续观看下一集式的花哨反馈。3.3 部署到服务器或托管平台构建完成后public/里的内容就是你要发布的所有产物。你可以选择多种方式上线方式一传统服务器rsync -avz --delete public/ useryour-server:/var/www/html/方式二对象存储托管阿里云 OSS 或者腾讯云 COS 之类的服务都支持从文件夹批量上传。上传完成后往往还要配置一下静态网站托管开关然后在控制台里找到分配的访问地址填到base_url里再重新构建一次保证链接正确。方式三Docker 镜像部署caveman 的静态产物可以用官方 Nginx 镜像包一下Dockerfile 简单到离谱FROM nginx:alpine COPY public/ /usr/share/nginx/html构建镜像推到仓库再启动容器几秒钟的事。我个人偏好的组合是本地caveman build配合脚本一键rsync到一台最低配的云服务器。这套流程跑起来之后发布这个动作的心理门槛降低了很多不再像以前一样要考虑各种流程就是敲一个命令十秒钟全部搞定。3.4 关于性能的一些实测我建了一个包含 500 篇文章的测试仓库做压力测试构建耗时在 1.2 秒左右老式 Intel 笔记本上跑的。生成的页面文件都是纯 HTML没有内联脚本的阻塞也没有外链的 CDN 依赖用 Lighthouse 跑分各项分数的满分概率极高。凡是经历过首屏等三秒才能交互那种重前端站点的人回到这种传统多页静态站点时会有一种久违的轻快感。4. 实战中遇到的常见问题与排查技巧4.1 构建后页面打不开这个问题的出现频率最高十次里头九次是因为路径问题。caveman 生成的都是相对路径的吗不一定。如果你在模板里写死了/assets/style.css而站点被托管在子目录下比如https://blog.example.com/caveman/这种那访问路径就会错。排查思路是先在本地用caveman server起服务打开浏览器开发者工具看 Network 里资源请求路径和实际文件路径的对应关系。还有一点构建之前先把caveman.toml里的base_url临时改成http://localhost:8080确认一切正常再改回正式域名重新构建。这一类问题排查完了90% 的白屏问题都能被消灭。4.2 模板里的循环不生效caveman 的模板循环语法是这样的{{ range .Posts }} div classpost-item h2a href{{ .URL }}{{ .Title }}/a/h2 /div {{ end }}常见错误是只写了一半闭合标签。它毕竟是 Go 模板那套语法对标签闭合有严格的要求。还有个小细节range内部的变量作用域会被 . 替换为当前遍历项如果你在循环里想访问站点全局变量就得写$.Site.Title拿全局上下文这个$符号是新手最容易漏掉的。4.3 Markdown 渲染结果和预览不一样这个我来来回回踩了不下三次。主流编辑器的 Markdown 预览和 caveman 内置的渲染引擎对换行处理有差异。部分编辑器采用 GFMGitHub Flavored Markdown规则两个普通换行不会生成新段落而 caveman 的默认渲染器认为是段落分隔。解决办法很简单段落之间就老老实实敲两个换行别只打一个。还有表格语法记得表头和分隔行之间必须有一个空行这个规则严格执行起来会避免很多看起来没渲染对的麻烦。4.4 本地可以预览服务器上却 404如果确认public/目录上传完整但服务器上出现了 404先看一下 Nginx/Apache 的伪静态规则。caveman 生成的是.html文件如果服务器配置了去掉扩展名的重写规则反而会造成访问/posts/hello-world找不到文件。一个最简单的排查方法直接访问带.html后缀的完整路径试试如果带后缀能打开但不带后缀打不开那就说明重写规则有问题。要么在后缀为html时关闭重写要么改造 URL 结构别在这一块纠结太久。4.5 关于标签与分类的若干细节caveman 支持在文章 Front Matter 里写tags和category默认配置下它会为每个标签生成一个独立的归档页。但默认模板里并没有归档页的样式设计——这需要你自己写。如果你没精力做也可以直接不填标签让它退化为全部文章列表模式。有些人可能会被强大到可以自动整理分类的预设立场束缚其实轻量的归档页功能已经足够满足多数个人站点了。4.6 排查思路速查表下面是我在实际使用中总结的一个快速排查清单任何不正常的现象先按顺序自查大部分问题都能在这张表里解决症状检查顺序最可能的坑页面样式全丢1. 模板路径 2. base_url 3. 资源文件命名资源引用写死绝对路径文章列表为空1. Front Matter 格式 2. 文件后缀 3. 目录位置YAML 缩进用了 Tab构建报错1. 模板标签闭合 2. 配置文件语法 3. 版本更新说明模板里用了新版本才支持的函数中文乱码1. 文件编码 2. 模板声明 3. HTTP 头文件存成了 GBK应统一为 UTF-85. 场景扩展与组合玩法5.1 搭建个人知识库或笔记系统caveman 这种目录即文件的结构天然适合做知识库。我现在的做法是在content/下面建了多个子目录分别放工作笔记、读书摘录和随想构建完就能得到一个可离线浏览的知识站点。配合rsync自动同步到服务器后手机浏览器也能随时访问。我之前用 Notion 的时候最大的问题是排版时忍不住改样式而且数据导出格式非常混乱用 caveman 之后彻底没这个顾虑了因为根本没有任何花哨的排版功能。5.2 作为产品文档站产品文档通常不大但需要版本管理。caveman 和 Git 配合得非常完美Markdown 天然支持 diff模板是纯文本构建产物丢弃也无所谓。我在 GitHub 上维护一套文档项目每次发版就新建一个分支然后用 CI 在 GitHub Actions 里执行caveman build再推送产物到 Pages 服务整个过程不需要在本地装任何额外开发环境。5.3 与自动化脚本配合因为构建命令只有一个二进制文件想把这套东西放进任何自动化流水线里都极其容易。比如我写过一个监控脚本每天从数据库导出统计数据塞进content/reports/下生成 Markdown然后调用caveman build生成报告页面。这个过程中没有奇怪的中间层也没有另一个运行环境的瓶颈。对于轻量数据可视化的需求这是个很灵活的方案。5.4 改造模板主题caveman 没有官方的主题市场我的印象中甚至没有一个集中下载的地方但换个模板的成本低到完全可以手写。我从零开始写了一个类似新闻简报的模板总共也就花了两天时间而且其中一天还是在调 CSS 的移动端适配。与其找现成主题我更推荐直接基于默认模板改。这种造轮子的过程会让你对整个站点的每个像素都了如指掌。5.5 不用构建工具能不能直接搭配 Tailwind 之类能但我不建议。caveman 的哲学是少就是多如果你非要引入 PostCSS、Tailwind CLI 这一整套构建链等于把已经扔掉的复杂度又从后门捡了回来。我个人的取舍是极简风格就用纯手写 CSS。如果你一定要用 Tailwind也请用它的 CDN 版至少别给自己找编译的麻烦。这类选择直接决定项目的长期维护成本值得慎重考虑。6. 一些不得不说的局限与取舍6.1 不适合的类型没有四舍五入的万能工具caveman 的边界也很清楚。如果要做一个千人互动的社区、带用户系统的 Web 应用或者想用 Vue/React 做前后端分离的前台别选它。它就是个从 Markdown 到 HTML的翻译官多余的活干不了也不该让它干。有人可能会说可以配合 Ajax 实现交互呀但在单机文件环境里这类方案往往绕一圈回来复杂度全堆在自己身上得不偿失。6.2 多语言支持官方没有提供多语言网站的一键方案。我实测下来如果你的站点需要中英文双语版本需要自己规划目录结构比如content/zh/和content/en/再在模板里手动判断当前文章属于哪个目录。可以做但毫无捷径。如果是内容频繁更新的双语团队项目这个方案维护成本会逐渐偏高。6.3 搜索功能没有内置搜索。最粗糙但有效的做法是生成一个纯客户端搜索页面把所有文章的标题和正文塞进一个 JSON 文件前端拿 JS 做过滤。内容多了以后这种方式肯定有性能瓶颈但对于几千篇文章以内的小站体验完全够用。我在本地测试时使用这个方案配合一份简单索引搜索平均响应时间也就是几十毫秒量级。6.4 关于社区与生态说实话caveman 的社区生态和 Hugo/Hexo 完全不在一个量级上没有Plugins广场也没有Theme市场。但这恰恰可能是一种优势——你不需要卷进工具链的军备竞赛它的一切都很稳定。如果你在网上搜到的大部分是英文资料也符合情理极简方案在中文圈子里讨论得不多大家更喜欢功能全的全家桶。7. 我最后的几条实操心得写到这里其实已经把这套工具的核心都讲透了。再说几句我折腾这一两周的体感它最值钱的地方不是快而是不打扰。以前的工具总会用生命周期钩子、插件机制、提醒更新弹窗来占据你的注意力而 caveman 只是安静地把你写的 Markdown 变成网页你甚至会忘记它本身的存在。一个小技巧你可以在content/_index.md的 Front Matter 里设置一个template: custom字段为此页面指定一份独立的模板。这样首页想做一个完全不一样的排版时不会干扰文章模板的结构。这种平时用不到但关键时刻救命的细节最能反映设计者对开发者体验的理解。还有一个好习惯是把构建产物的public/目录加进.gitignore。既然它能随时从源文件重建就没有必要把生成物纳入版本控制。有人喜欢把产物也 Push 上去来免服务器构建那是另一个取舍但建议至少保持源目录的清爽。最后再分享一个关于要不要选它的判断标准问一下自己——如果你三个月后需要重新把这个站迁移到另一台机器上你愿意为此付出多少时间去回忆当初的环境配置如果答案是半小时以内搞定那就值得选。按这个标准caveman 毫无疑问是很合格的。工具是为人服务的能把为人服务这件事做干净就已经很难得了。
