[{"content":"这是一个 Hugo + Stack 主题搭起来的博客骨架。这篇文章的作用是：三个月后你（或者帮你维护的人）回来看，能立刻知道每个文件是干什么的。\n目录结构 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 blog/ ├── config/_default/ # 站点配置，按职责拆成 4 个文件 │ ├── hugo.toml # 基础：域名、语言、永久链接 │ ├── params.toml # 主题参数：侧栏、卡片、组件 │ ├── menu.toml # 导航与社交图标 │ ├── markup.toml # Markdown 渲染 / 代码高亮 │ └── related.toml # 相关文章排序权重 ├── content/ │ ├── post/ # 文章（每篇一个目录） │ │ └── start-here/ │ │ └── index.md # 只放正文；本站不用封面图 │ └── page/ # 关于 / 归档 / 搜索 等固定页 ├── assets/ │ ├── scss/custom.scss # 所有视觉改动只写这里 │ └── img/avatar.png └── themes/stack/ # git submodule，不要改 写一篇新文章 1 hugo new post/文章目录名/index.md 生成后直接写正文。本站不用封面图，front matter 里不要写 image:——写了但图不存在，主题会把 Featured image of post 标题 这串 alt 文字当内容显示在卡片上，看起来像多了一行标题。\n用目录而不是单个 .md 文件，是为了让将来要放的文章配图跟着文章走——迁移、删除、备份都不会留下孤儿图。\n图片要不要跟正文同目录 Hugo 的图片处理（缩放、生成 srcset、构建期取主色）只对页面资源生效，也就是和 index.md 同目录的文件。放在 static/ 里的图片会被原样拷贝，既不压缩也不生成多分辨率版本。\n正文用图建议还是放同目录。几百张之后，更合理的做法是放到对象存储或图床，Markdown 里直接写完整 URL。\n常用命令 1 2 3 hugo server -D # 本地预览，含草稿 hugo --gc --minify # 生产构建到 public/ hugo new post/xxx/index.md 构建产物在 public/，已加入 .gitignore。部署时把它同步到服务器即可，不需要在服务器上装任何运行时。\n记一笔字数 中文写作时 Hugo 的 .Summary 依赖 hasCJKLanguage = true，已在 hugo.toml 里打开。没开的话，摘要会按空格切词，中文会被当成一个超长单词处理，首页摘要全部失效。\n配置项 作用 当前值 hasCJKLanguage 中文分词与字数统计 true pagination.pagerSize 每页文章数 6 permalinks.post 文章 URL 规则 /p/:slug/ 改配色不要去动 themes/stack，全部写在 assets/scss/custom.scss 里——主题升级时你的改动不会被覆盖。\n","date":"2026-10-31T21:00:00+08:00","permalink":"/p/start-here/","title":"从这里开始"},{"content":"#34495e 这个颜色有个很好的性质：它足够暗，所以配白字时对比度够（约 8.9:1），可以当按钮底色；但它又带了一点蓝，不像纯灰那样死板。把它放在冷灰底上，整页会呈现出一种\u0026quot;未被阳光直射的蓝\u0026quot;的感觉。\n三层分工 一套主色要成立，不能只定义一种颜色，得定义它在不同上下文里的三个身份。\n角色 亮色值 深色值 用在哪 主色 #34495e #9db8cf 标签底、卡片标题强调 主色加深 #22303d #c3d5e4 hover、当前菜单项 主色文字 #ffffff #10151a 盖在主色上的字 深色模式下主色必须反过来变浅。直接把 #34495e 放到深色背景上，标签会糊成一团黑块，这是深色模式最常见的失误。\n底色不要太纯 背景用 #eef1f5 而不是纯白或 #f5f5fa。原因很实际：\n纯白背景上，白色卡片没有边界，只能靠阴影，容易显脏； #f5f5fa 带一点紫，和冷灰蓝主色放在一起会有微妙的色调冲突； #eef1f5 是蓝灰的浅色版本，和主色同一条色轴，卡片压上去自然有层次。 1 2 3 4 5 :root { --body-background: #eef1f5; --card-background: #ffffff; --card-separator-color: rgba(52, 73, 94, 0.11); } 那条 rgba(52,73,94,.11) 的描边是关键：1px，几乎看不见，但它把卡片从背景里\u0026quot;抬\u0026quot;起来了，比加深阴影干净得多。\n正文里不要用下划线 中文的行高和字面率都大，链接加下划线会和汉字笔画打架，尤其小字号时整段会显得毛躁。改用淡色底衬托：\n1 2 3 4 5 :root { --link-background-color: 52, 73, 94; --link-background-opacity: 0.14; --link-background-opacity-hover: 0.24; } 这个变量接受的是 RGB 三元组，不是十六进制——写成 #34495e 会静默失效，链接底色直接消失，且没有任何报错。这类\u0026quot;变量格式不对但不报错\u0026quot;的坑，是自定义主题变量时最耗时间的部分。\n对比度校验 调完颜色别凭眼睛判断。正文、次要文字、标签这三类至少要满足：\n正文正文 #1d2833 on #ffffff → 14.2:1 次要文字 #56636f on #ffffff → 5.9:1 标签白字 on #34495e → 8.9:1 都过了 WCAG AA。真要压到 21:1 那种极致，页面会失去层次——4.5:1 之上再多，眼睛感受到的提升远小于视觉上的僵硬。\n一句话原则：主色负责态度，底色负责呼吸，描边负责秩序。\n","date":"2026-10-30T20:10:00+08:00","permalink":"/p/slate-blue/","title":"冷灰蓝：一套克制的主色"},{"content":"选 Hugo 的主要理由是构建速度，但\u0026quot;几千篇\u0026quot;这个量级上，构建从来不是第一个崩的地方。先崩的通常是首页体积、客户端搜索索引，以及图片托管。\n构建：几秒的事 Hugo 没有增量构建，每次都是全量。听起来可怕，实际上 3000 篇纯文本的构建时间取决于模板复杂度而不是文章数——大多数时间花在图片处理和模板渲染上，而不是解析 Markdown。\n真正会拖慢构建的是这三件事，按影响排序：\n图片处理。每张封面生成 4 个宽度 × WebP/JPEG 两套 = 8 个文件。3000 篇就是 24000 次编码。这是唯一值得做缓存的地方（Hugo 会自动缓存到 resources/_gen，但 CI 上每次都是冷的）。 没有 partialCached 的循环内 partial。侧栏、页脚、图标这类与页面无关的片段，在文章循环里逐个调用就是灾难。 taxonomy 页爆炸。每个标签一页，每个标签的分页再乘一层。标签数量失控时页面数会以乘积增长。 1 2 # 看一眼到底慢在哪 hugo --templateMetrics --templateMetricsHints 首页体积 如果首页用大卡片封面流，代价是每张卡片都要一张真实图片。6 张卡片 × 每张 ~200KB（1080 宽，WebP）≈ 1.2MB——已经超过一个中文文字页面的合理预算。本站干脆不用封面，首页卡片只有文字，这条账直接归零。\n如果以后要加回封面，三条硬约束：\n封面必须走 srcset，手机上不能下载桌面尺寸； 首屏之外用 loading=\u0026quot;lazy\u0026quot;（主题已默认处理）； 列表页封面宽度上限压到 1080，不要用原图。 1 2 3 4 5 \u0026lt;img srcset=\u0026#34;cover-720.webp 720w, cover-1080.webp 1080w, cover-1440.webp 1440w\u0026#34; sizes=\u0026#34;(max-width: 767px) calc(100vw - 30px), 950px\u0026#34; loading=\u0026#34;lazy\u0026#34; /\u0026gt; 搜索索引：最容易被忽略的死角 Stack 主题的搜索是纯客户端的：构建时生成一个 index.json，浏览器把全部文章的标题、标签、正文摘要拉下来，在本地做匹配。\n3000 篇时这个文件会到 2–4MB。用户的搜索框还没用上，流量已经花掉了。\n到那个规模，换 Pagefind：\n1 pagefind --site public 它在构建后扫描 public/，把索引切成几百个小分片，查询时只下载相关的几片。首次搜索的加载量从 MB 级降到几十 KB，而且索引是压缩过的静态文件，不需要任何服务端。\n代价是它只能搜到已经渲染进 HTML 的内容——对博客来说完全够用。\n图片托管 正文配图放在文章目录里（page bundle）是最省心的，因为 Hugo 的图片处理只认页面资源。但几千篇 × 每篇几张图，仓库很快就会到 GB 级，git clone 变成一次小型下载。\n两种解法：\n方案 优点 代价 对象存储 + image: 写完整 URL 仓库干净，CDN 加速 依赖外部服务，构建时需要联网抓图 独立图片仓库 + jsDelivr 免费 CDN，git 管理 国内访问不稳定 如果要长期自托管，第一种更稳；构建机上给 resources.GetRemote 配一个本地缓存目录，冷构建的联网开销就只在第一次发生。\n排序：什么时候该改 最后一件小事。默认按日期倒序，但写了几年之后，你可能会想让\u0026quot;常青文章\u0026quot;（教程、入门指南）排在新文章前面。Hugo 支持按自定义权重排序：\n1 2 [frontmatter] weight = \u0026#34;:default\u0026#34; 在常青文章里写 weight: 10，其余不写，就能把置顶做出来而不影响日期归档。这比手动改 date 干净得多。\n规模上来以后，值得优化的顺序是：图片 → 搜索 → 模板 → 构建。构建放最后，因为它本来就快。\n","date":"2026-10-28T09:30:00+08:00","permalink":"/p/at-scale/","title":"几千篇文章之后的性能账"}]