当前位置：首页 > news >正文

SUMTEC：轻量级博客内核的六模块设计与实战

news 2026/6/16 15:50:37

1. 项目概述：一个被低估的轻量级博客系统内核

“SUMTEC — There’s a thing in my bloglet.” 这句话乍看像一句带点英式冷幽默的自言自语，实则藏着一套极简但逻辑严密的博客构建哲学。我第一次在 GitHub 上看到这个仓库时，没点开 README 就先被标题击中了——它不叫 “SUMTEC Blog Engine” 或 “SUMTEC Static Site Generator”，而是用 bloglet（blog + booklet 的合成词）这个生造词，精准锚定了它的定位：不是博客平台，不是 CMS，甚至不是传统意义上的静态站点生成器；它是一个可嵌入、可裁剪、可复用的博客内容处理内核。核心关键词 SUMTEC 并非缩写，而是一个自定义命名：S（Structure）、U（URL routing）、M（Markup processing）、T（Template binding）、E（Export logic）、C（Configuration layer）。六个字母对应六个不可拆解的职责模块，每个模块都只做一件事，且只做好这一件事。

我在过去八年里维护过 7 个不同技术栈的个人博客（从 WordPress 插件定制到 Hugo 主题魔改，再到自己手写的 Node.js SSR 博客服务），也给三家公司做过内部知识库系统。反复踩坑后发现，90% 的“博客系统臃肿”问题，根源不在功能多，而在职责混杂：路由逻辑和模板渲染耦合、内容解析和元数据提取绑死、导出格式和存储路径强绑定。SUMTEC 的设计恰恰反其道而行之——它把博客最底层的“内容生命周期”切成了六段独立流水线，每段都提供清晰接口、默认实现和替换钩子。比如它的 Markup processing 模块，默认用 remark（而非 markdown-it 或 commonmark），不是因为 remark 更快，而是因为它原生支持插件链式调用，能让你在解析 Markdown 的同时注入自定义 AST 节点（比如把{{readtime}}替换成实际阅读时长，或把![](path.jpg)自动转为带loading="lazy"和decoding="async"的<picture>标签）。这种设计让“加功能”变成“接插件”，而不是“改源码”。适合谁？适合那些厌倦了每次升级 Hugo 就要重调主题、受够了 WordPress 插件冲突、又觉得 Next.js 太重的中级以上前端/全栈开发者；也适合想用最小成本给产品文档站加博客模块的产品技术团队。它不解决“怎么部署”，但彻底理清了“内容从哪来、到哪去、中间怎么变”的底层脉络。

2. 内容整体设计与思路拆解：为什么是这六个模块？

2.1 SUMTEC 的六边形架构本质

SUMTEC 不是 MVC，也不是 MVVM，它采用的是更贴近内容工作流的六边形职责分层模型。这不是为了炫技，而是源于对真实写作场景的观察：一个作者写完一篇.md文件后，真正需要的不是“渲染成 HTML”，而是“让这篇内容在正确的时间、以正确的形式、出现在正确的上下文中”。这个“正确”由六个维度共同定义：

S（Structure）：定义内容的组织骨架。它不关心文件存在哪，只约定“一篇博文必须有title、date、slug、tags四个必填字段”，且date必须是 ISO 8601 格式。我试过把_posts/2023-01-01-hello.md改成posts/hello-20230101.md，只要 frontmatter 里date: "2023-01-01"存在，SUMTEC 就能识别。它甚至允许你用 YAML、TOML 或 JSON 写 frontmatter，因为 Structure 层只做字段校验，不做格式解析——那是下一个模块的事。
U（URL routing）：负责将内容 ID 映射到最终 URL 路径。它的默认规则是/blog/:year/:month/:slug/，但你可以通过配置覆盖为/journal/:slug.html或/notes/:id。关键在于，U 层完全不知道内容长什么样，它只接收一个结构化对象（含id、slug、date等字段），输出一个字符串路径。这意味着你可以轻松实现“同一内容多端发布”：给 Web 端输出/blog/2024/05/my-post/，给 RSS 输出/feed/2024/05/my-post.xml，给 PDF 导出输出/pdf/my-post.pdf，全部复用同一套路由逻辑。
M（Markup processing）：这是 SUMTEC 最具延展性的模块。它基于 remark 插件生态，但做了两处关键改造：第一，强制所有插件必须声明输入/输出 schema（比如remark-math插件必须标注它只处理包含$$的段落，且输出为<div class="math">）；第二，引入“处理阶段”概念（preprocess→transform→postprocess）。我曾用这个机制实现了“自动摘要生成”：在preprocess阶段用正则提取前 300 字，在transform阶段插入<summary>标签，在postprocess阶段把摘要文本塞进frontmatter.summary字段。整个过程不碰原始 Markdown 字符串，只操作 AST，稳定性和可测试性远超字符串替换方案。
T（Template binding）：它不提供模板引擎（如 Nunjucks 或 EJS），而是定义了一套数据绑定契约。模板文件（.njk或.html）里只能使用{{ post.title }}、{{ post.content }}这类扁平字段，禁止{{ post.tags | join(', ') }}这类过滤器。为什么？因为 T 层只负责“把数据灌进去”，格式化工作交给 M 层的 postprocess 插件。这样做的好处是：同一个post.content字段，在 Web 模板里是带<picture>标签的 HTML，在 RSS 模板里是纯文本（由 M 层另一个插件负责 strip HTML），在邮件推送模板里是带 emoji 的富文本（由第三个插件注入）。数据源唯一，表现形式无限。
E（Export logic）：它不生成文件，只生成“导出任务队列”。每个任务包含三个要素：目标路径（由 U 层提供）、源数据（由 T 层渲染）、导出方式（writeFile、writeToS3、sendToAPI）。这意味着你可以让一篇博文同时写入本地dist/目录、上传到 Cloudflare R2、并触发 Slack 通知 webhook，所有动作在一个 export cycle 内完成，且失败可单独重试。我在线上环境配置了 S3 导出失败自动降级到本地备份，就是靠 E 层的任务状态机实现的。
C（Configuration layer）：这是 SUMTEC 的“胶水层”，但它不写死任何配置项。所有配置都通过sumtec.config.js导出一个函数，该函数接收环境变量（process.env.NODE_ENV）和运行时参数（如--watch），动态返回配置对象。比如开发时启用liveReload: true，生产时关闭；CI 环境下export: ['s3', 'rss']，本地调试时export: ['filesystem']。这种设计让配置不再是静态清单，而是可编程的决策逻辑。

提示：SUMTEC 的核心思想是“模块间仅通过契约通信，不共享状态”。S 层输出结构化数据，U 层只读取其中id和date，M 层只处理content字段，T 层只消费post对象……这种松耦合让每个模块都能独立演进。比如你想换掉 remark，只需实现一个符合 M 层接口的新模块（输入 Markdown 字符串，输出 AST 对象），其他五个模块完全不用动。

2.2 为什么拒绝“一站式”？——来自真实项目的教训

2022 年我帮一家硬件公司做产品文档站，他们要求“博客功能要和文档共用导航栏、搜索、用户登录”。当时选了 Hexo，结果卡在第三周：Hexo 的主题系统把博客和文档硬编码成两个独立路由，要合并导航必须 fork 主题并重写 layout。后来我们切到 SUMTEC，只用了两天：用 S 层统一管理文档和博客的元数据结构（都加type: 'doc'或type: 'post'字段），U 层配置/docs/:slug/和/blog/:slug/两条路由，M 层用不同插件链处理两类内容（文档用remark-admonitions渲染警告框，博客用remark-gfm支持表格），T 层共用一个layout.njk模板，通过{{ post.type === 'doc' ? 'Docs' : 'Blog' }}切换面包屑。整个过程没有改一行 Hexo 源码，也没有写任何 hack 代码。

这就是 SUMTEC 的底层优势：它不预设“博客是什么”，只定义“博客内容如何流动”。当你需要把博客嵌入现有系统时，它不是要你“适配它”，而是让你“用它适配你”。

3. 核心细节解析与实操要点：从零启动一个 SUMTEC 博客

3.1 初始化项目与目录结构设计

SUMTEC 不提供create-sumtec-app脚手架，官方推荐的手动初始化方式反而更体现其设计哲学。我建议按以下结构组织项目（已验证在 12 个不同规模项目中稳定运行）：

my-blog/ ├── content/ # 所有源内容（Markdown + 前置数据） │ ├── posts/ # 博文主目录 │ │ ├── 2024-05-01-my-first-post.md │ │ └── 2024-05-15-deep-dive-into-sumtec.md │ ├── pages/ # 静态页面（about, contact） │ └── assets/ # 原始图片、SVG 等（未处理） ├── src/ # SUMTEC 核心配置与扩展 │ ├── config/ # 配置文件 │ │ ├── index.js # 主配置入口 │ │ └── routes.js # 路由规则定义 │ ├── plugins/ # 自定义 remark 插件 │ │ ├── auto-summary.js │ │ └── image-optimizer.js │ └── templates/ # 模板文件 │ ├── layouts/ │ │ └── base.njk │ └── pages/ │ ├── post.njk │ └── index.njk ├── dist/ # 构建输出目录（gitignore） ├── sumtec.config.js # SUMTEC 入口配置 └── package.json

关键设计点：

content/ 与 src/ 物理隔离：内容作者（市场部同事）只需编辑content/posts/下的.md文件，无需接触src/中的任何代码。这种隔离让非技术人员也能安全贡献内容。
assets/ 目录不参与构建流程：SUMTEC 默认不处理二进制文件，图片优化由plugins/image-optimizer.js在 M 层完成（将![](cat.jpg)转为响应式<picture>），原始图片保留在content/assets/供设计师管理。
templates/ 下无全局变量：每个模板文件只接收明确传入的数据（如post.njk只接收{ post }对象），杜绝了传统模板引擎中site.title这类隐式依赖，提升可测试性。

注意：SUMTEC 的content/目录名可任意修改（如src/content或docs/），只要在sumtec.config.js中正确指向即可。我见过最极端的案例是某团队把content/放在 Git 子模块中，主项目只存配置，内容由另一个仓库独立管理——这正是 SUMTEC 松耦合设计带来的灵活性。

3.2 配置文件详解：sumtec.config.js 的编写艺术

sumtec.config.js是 SUMTEC 的心脏，它必须导出一个函数，而非对象。这是为了支持环境感知配置。以下是我生产环境使用的精简版配置（已去除敏感信息）：

// sumtec.config.js const path = require('path'); const { createConfig } = require('@sumtec/core'); module.exports = (env) => { // 1. 基础路径配置（所有路径必须绝对） const CONTENT_DIR = path.resolve(__dirname, 'content'); const TEMPLATES_DIR = path.resolve(__dirname, 'src/templates'); const OUTPUT_DIR = path.resolve(__dirname, 'dist'); // 2. 环境判断（env 来自 CLI 参数或 process.env） const isProduction = env.NODE_ENV === 'production'; const isWatchMode = env.watch === true; // 3. 动态配置对象 return createConfig({ // S 层：内容结构定义 structure: { contentDir: CONTENT_DIR, collections: { posts: { pattern: 'posts/**/*.md', fields: ['title', 'date', 'slug', 'tags', 'excerpt'], required: ['title', 'date'] }, pages: { pattern: 'pages/**/*.md', fields: ['title', 'slug', 'layout'], required: ['title', 'slug'] } } }, // U 层：路由规则（支持正则和函数） routing: { rules: [ { collection: 'posts', // 函数式路由：可根据 post 数据动态生成路径 path: (post) => { const date = new Date(post.date); return `/blog/${date.getFullYear()}/${String(date.getMonth() + 1).padStart(2, '0')}/${post.slug}/`; } }, { collection: 'pages', path: (page) => `/pages/${page.slug}/` } ] }, // M 层：Markdown 处理链（顺序即执行顺序） markup: { processor: 'remark', plugins: [ // 预处理：提取摘要、清洗空格 require('./src/plugins/auto-summary'), [require('remark-gfm'), {}], // 表格、删除线等 [require('remark-math'), { singleDollarTextMath: false }], // 后处理：图片优化、链接补全 require('./src/plugins/image-optimizer'), [require('remark-external-links'), { target: '_blank', rel: 'noopener' }] ] }, // T 层：模板绑定 template: { engine: 'nunjucks', templatesDir: TEMPLATES_DIR, layouts: { default: 'layouts/base.njk' } }, // E 层：导出逻辑 export: { outputDir: OUTPUT_DIR, targets: [ { type: 'filesystem', options: { // 开发时只导出 HTML，生产时加 RSS 和 Sitemap include: isProduction ? ['html', 'rss', 'sitemap'] : ['html'] } } ] }, // C 层：运行时配置 watch: isWatchMode, liveReload: isDevelopment && isWatchMode, verbose: true }); };

这个配置的关键在于所有模块配置都可编程。比如routing.rules中的path字段支持函数，让我能实现“根据标签自动归档”：如果post.tags.includes('tutorial')，就路由到/tutorials/:slug/；否则走默认/blog/:slug/。再比如markup.plugins数组里，我用require()动态加载本地插件，避免 npm install 第三方插件带来的版本锁定风险。

实操心得：不要在sumtec.config.js中写业务逻辑！我曾在一个项目里把“根据日期自动设置文章状态（draft/published）”的逻辑写进配置，结果导致 CI 构建时时间戳不一致，部分文章被误判为草稿。正确做法是：在 S 层的collections.posts.fields中增加status字段，由作者在 frontmatter 中显式声明status: published，配置文件只做校验，不作推断。SUMTEC 的哲学是“显式优于隐式”。

3.3 自定义插件开发：image-optimizer.js 的完整实现

SUMTEC 的 M 层插件是其延展性的核心。下面是我为图片优化编写的src/plugins/image-optimizer.js，它实现了三项关键能力：自动添加srcset、生成 WebP 备用图、注入懒加载属性。代码经过生产环境 18 个月验证，处理过 2300+ 张图片：

// src/plugins/image-optimizer.js const fs = require('fs').promises; const path = require('path'); const sharp = require('sharp'); // 需要 npm install sharp const { visit } = require('unist-util-visit'); // 预定义尺寸（适配主流设备） const SIZES = [ { width: 400, name: 'sm' }, { width: 800, name: 'md' }, { width: 1200, name: 'lg' }, { width: 1600, name: 'xl' } ]; // 缓存已处理图片路径，避免重复生成 const processedImages = new Map(); module.exports = function imageOptimizer() { return async function transformer(tree, file) { // 只处理 Markdown 文件 if (!file.extname || file.extname !== '.md') return; // 遍历 AST 中所有 image 节点 visit(tree, 'image', async (node) => { const imagePath = node.url; const imageDir = path.dirname(imagePath); const imageName = path.basename(imagePath, path.extname(imagePath)); const imageExt = path.extname(imagePath).toLowerCase(); // 跳过非本地图片（如 CDN 链接） if (!imagePath.startsWith('./') && !imagePath.startsWith('../')) return; // 解析相对路径为绝对路径 const absImagePath = path.resolve(path.dirname(file.path), imagePath); const absImageDir = path.dirname(absImagePath); // 检查文件是否存在 try { await fs.access(absImagePath); } catch { console.warn(`[SUMTEC] Image not found: ${absImagePath}`); return; } // 生成优化后图片路径（缓存键） const cacheKey = `${absImagePath}-${SIZES.map(s => s.width).join('-')}`; if (processedImages.has(cacheKey)) { node.url = processedImages.get(cacheKey); return; } // 创建输出目录 const outputDir = path.join(absImageDir, 'optimized'); await fs.mkdir(outputDir, { recursive: true }); // 生成多尺寸 WebP 图片 const webpPaths = []; for (const size of SIZES) { const outputPath = path.join( outputDir, `${imageName}-${size.name}.webp` ); try { await sharp(absImagePath) .resize(size.width) .webp({ quality: 80 }) .toFile(outputPath); webpPaths.push({ path: outputPath, width: size.width }); } catch (err) { console.error(`[SUMTEC] Failed to optimize ${absImagePath} for ${size.name}:`, err); } } // 生成 srcset 字符串 const srcset = webpPaths .map(({ path, width }) => { const relPath = path.relative(path.dirname(file.path), path); return `${relPath} ${width}w`; }) .join(', '); // 修改 AST 节点：用 picture 标签替代原始 image const pictureNode = { type: 'html', value: ` <picture> <source media="(min-width: 1200px)" srcset="${webpPaths.find(w => w.width === 1600)?.path?.replace(/\\/g, '/') || ''} 1600w, ${webpPaths.find(w => w.width === 1200)?.path?.replace(/\\/g, '/') || ''} 1200w" type="image/webp"> <source media="(min-width: 768px)" srcset="${webpPaths.find(w => w.width === 800)?.path?.replace(/\\/g, '/') || ''} 800w, ${webpPaths.find(w => w.width === 400)?.path?.replace(/\\/g, '/') || ''} 400w" type="image/webp"> <img src="${webpPaths[0]?.path?.replace(/\\/g, '/') || node.url}" alt="${node.alt || ''}" loading="lazy" decoding="async" width="${webpPaths[0]?.width || '100%'}" height="auto"> </picture> `.trim() }; // 替换原节点 node.type = 'html'; node.value = pictureNode.value; // 缓存结果 processedImages.set(cacheKey, pictureNode.value); }); }; };

这个插件体现了 SUMTEC 插件开发的三个黄金原则：

AST 优先：不操作原始字符串，只修改 AST 节点，保证 Markdown 语法完整性；
副作用可控：所有文件 I/O（创建目录、写入图片）都在transformer函数内完成，不污染全局状态；
错误降级：当某张图片优化失败时，插件会保留原始<img>标签，确保构建不中断。

注意事项：sharp库在 Windows 上可能因 libvips 二进制缺失报错。我的解决方案是在package.json中添加optionalDependencies：
"optionalDependencies": { "sharp": "^0.32.5" }
并在插件开头加兜底逻辑：
try { const sharp = require('sharp'); } catch (e) { console.warn('[SUMTEC] sharp not available, skipping image optimization'); return; // 直接跳过处理 }

4. 实操过程与核心环节实现：构建一个可发布的博客

4.1 从零开始的完整构建流程

假设你已按 3.1 节创建好目录结构，现在执行以下步骤（全程在终端中操作，我用的是 macOS，Windows 用户请将npx替换为npm exec）：

第一步：安装 SUMTEC 核心包

npm init -y npm install @sumtec/core @sumtec/cli --save-dev

注意：SUMTEC 不提供全局 CLI，所有命令都通过npx调用，避免全局污染。@sumtec/cli是唯一需要安装的命令行工具，它只负责解析参数、加载配置、触发构建循环。

第二步：创建首篇博文在content/posts/2024-05-01-hello-sumtec.md中写入：

--- title: "Hello, SUMTEC" date: "2024-05-01" slug: "hello-sumtec" tags: ["getting-started", "sumtec"] excerpt: "A minimal introduction to the SUMTEC bloglet philosophy." --- # Welcome to SUMTEC This is your first blog post. SUMTEC processes this Markdown file through six independent modules: - **S**: Validates `title` and `date` fields - **U**: Routes it to `/blog/2024/05/hello-sumtec/` - **M**: Converts `# Welcome` to `<h1>` and optimizes images - **T**: Binds data to `post.njk` template - **E**: Writes HTML to `dist/blog/2024/05/hello-sumtec/index.html` - **C**: Uses environment-aware configuration Try editing this file — with `--watch`, changes will auto-rebuild.

第三步：编写基础模板创建src/templates/layouts/base.njk：

<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>{% if post %}{{ post.title }} | {% endif %}My Blog</title> <link rel="stylesheet" href="/css/main.css"> </head> <body> <header> <nav> <a href="/">Home</a> <a href="/blog/">Blog</a> <a href="/about/">About</a> </nav> </header> <main> {% block content %}{% endblock %} </main> <footer> <p>&copy; {{ "now" | date("%Y") }} My Blog. Built with SUMTEC.</p> </footer> </body> </html>

创建src/templates/pages/post.njk：

{% extends "layouts/base.njk" %} {% block content %} <article class="post"> <header class="post-header"> <h1>{{ post.title }}</h1> <time datetime="{{ post.date }}">{{ post.date | date("MMMM DD, YYYY") }}</time> {% if post.tags %} <div class="tags"> {% for tag in post.tags %} <span class="tag">{{ tag }}</span> {% endfor %} </div> {% endif %} </header> <div class="post-content"> {{ post.content | safe }} </div> <footer class="post-footer"> <p>Reading time: {{ post.readingTime }} minutes</p> </footer> </article> {% endblock %}

第四步：运行构建

# 一次性构建 npx sumtec build # 开发模式（监听文件变化） npx sumtec build --watch # 生产构建（启用所有导出目标） NODE_ENV=production npx sumtec build

构建成功后，dist/目录结构如下：

dist/ ├── blog/ │ └── 2024/ │ └── 05/ │ └── hello-sumtec/ │ └── index.html ├── pages/ │ └── index.html # 自动生成的首页（需额外配置） ├── rss.xml # 如果配置了 RSS 导出 └── sitemap.xml # 如果配置了 Sitemap 导出

实测心得：首次构建耗时约 3.2 秒（M1 MacBook Pro），处理 100 篇博文时平均 8.7 秒。比 Hugo（12.4 秒）快 30%，比 Next.js 静态导出（22.1 秒）快 60%。性能优势主要来自 SUMTEC 的“按需处理”：它只解析被路由规则匹配的文件，而 Hugo 会扫描整个content/目录，Next.js 会启动完整 React 渲染流水线。

4.2 首页与列表页的生成逻辑

SUMTEC 不自动生成首页（/index.html）或归档页（/blog/），这需要你手动配置。这是刻意为之的设计：避免“默认行为”绑架你的信息架构。以下是实现/blog/归档页的标准做法：

1. 在sumtec.config.js的structure.collections中添加archive集合：

collections: { posts: { /* ... */ }, archive: { // 这不是一个真实目录，而是虚拟集合 pattern: '', // 空字符串表示不扫描文件 fields: ['posts'], // 只需要 posts 字段 required: ['posts'] } }

2. 创建src/plugins/generate-archive.js插件：

// src/plugins/generate-archive.js const { createPage } = require('@sumtec/core'); module.exports = function generateArchive() { return async function transformer(tree, file) { // 此插件不处理 Markdown，只在构建末期生成页面 if (file.extname !== '.md') return; // 获取所有已处理的 posts const posts = file.data.collections?.posts || []; // 按日期倒序排列 const sortedPosts = [...posts].sort((a, b) => new Date(b.date) - new Date(a.date) ); // 创建虚拟页面数据 const archivePage = createPage({ id: 'archive', slug: 'blog', title: 'Blog Archive', content: '', posts: sortedPosts.slice(0, 10) // 只显示最新 10 篇 }); // 注入到全局数据中 file.data.collections.archive = [archivePage]; }; };

3. 在sumtec.config.js的markup.plugins中注册：

plugins: [ require('./src/plugins/generate-archive'), // ... 其他插件 ]

4. 创建src/templates/pages/archive.njk：

{% extends "layouts/base.njk" %} {% block content %} <h1>Latest Posts</h1> <ul class="post-list"> {% for post in collections.archive[0].posts %} <li class="post-item"> <a href="{{ post.url }}">{{ post.title }}</a> <time>{{ post.date | date("MMM DD, YYYY") }}</time> {% if post.excerpt %} <p>{{ post.excerpt }}</p> {% endif %} </li> {% endfor %} </ul> {% endblock %}

5. 在routing.rules中添加归档页路由：

{ collection: 'archive', path: '/blog/' }

这样，访问/blog/就会显示最新 10 篇博文的摘要列表。整个过程没有修改 SUMTEC 源码，全部通过插件和配置完成，完美体现其“可组合”特性。

4.3 部署到静态托管平台的实操技巧

SUMTEC 构建产物是纯静态文件，可部署到任何静态托管平台。以下是我在 Vercel、Cloudflare Pages 和 GitHub Pages 上的实操经验：

Vercel 部署：

在项目根目录创建vercel.json：

{ "version": 3, "builds": [ { "src": "package.json", "use": "@vercel/static-build", "config": { "distDir": "dist" } } ], "routes": [ { "src": "/(.*)", "dest": "/dist/$1" } ] }

关键技巧：在vercel.json中设置"outputDirectory": "dist"，Vercel 会自动检测并跳过构建步骤，直接上传dist/目录，部署时间从 42 秒降至 8 秒。

Cloudflare Pages 部署：

构建命令：npx sumtec build
输出目录：dist
关键技巧：在wrangler.toml中添加：

[build] command = "npx sumtec build" publish = "dist" [env.production] build.command = "NODE_ENV=production npx sumtec build"

这样可以为生产环境启用 RSS 和 Sitemap 导出，而预览环境只构建 HTML，节省构建资源。

GitHub Pages 部署：

使用 GitHub Actions，.github/workflows/deploy.yml：

name: Deploy to GitHub Pages on: push: branches: [main] paths: ['content/**', 'src/**', 'sumtec.config.js'] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v3 - name: Setup Node.js uses: actions/setup-node@v3 with: node-version: '18' - name: Install dependencies run: npm ci - name: Build with SUMTEC run: npx sumtec build - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./dist

关键技巧：在on.push.paths中精确指定触发路径，避免每次提交README.md都触发构建，提升 CI 效率。

注意事项：所有托管平台都要求dist/目录下的index.html作为入口。SUMTEC 默认不生成dist/index.html，你需要在routing.rules中为首页添加一条规则：
{ collection: 'pages', path: '/', // 指向 content/pages/home.md 或其他文件 }
或者用generate-archive.js插件生成一个虚拟首页。

5. 常见问题与排查技巧实录：那些只有踩过才懂的坑

5.1 路由冲突：为什么我的`/blog/`页面打不开？

现象：访问https://example.com/blog/返回 404，但https://example.com/blog/2024/05/hello-sumtec/正常。

排查思路：

检查sumtec.config.js中routing.rules是否为archive集合配置了path: '/blog/'；
检查dist/目录下是否存在dist/blog/index.html（注意不是dist/blog/目录）；
查看构建日志，搜索Generating route，确认是否输出了/blog/的生成记录。

根本原因：SUMTEC 的路由规则是“路径匹配”，不是“目录匹配”。path: '/blog/'会生成dist/blog/index.html，而某些托管平台（如 GitHub Pages）要求dist/blog/index.html存在才能响应/blog/请求。如果生成的是dist/blog.html，则路径不匹配。

解决方案：