静态站生成脚本:38 个页面 2.4 秒构建
这个站点的 38 个页面由一份 640 行的 Python 脚本生成,2.4 秒跑完,没有任何第三方依赖。脚本同时还产出 sitemap、分页与目录页,改一次导航只动一个列表。
这一期要解的问题
用现成的静态站框架,导航改一项要动模板与配置两处,分页要靠插件,目录页要手写。页面一多,改一次导航就得翻十几个文件,还容易漏。自写脚本的好处是所有页面从一个数据结构里长出来,导航、面包屑、相关链接都从同一份数据里取,改一处全站同步。
零依赖不是洁癖,是维护成本。框架的插件生态会在两年内变动两轮,而一份 640 行的脚本,两年后你自己还能读懂。这一期把脚本拆成模板层、数据层、渲染层、检查层四块,逐块讲清职责边界。
脚本的四层结构
- 第 1 层 数据:一个 dict 管全站页面,字段含路径、标题、描述、导航位置
- 第 2 层 模板:13 个片段函数,用字符串拼接而不是模板引擎,避免引入依赖
- 第 3 层 渲染:把数据与片段组合成 HTML,统一转义与缩进
- 第 4 层 检查:渲染完立刻跑一遍链接存在性、标题唯一性、图片 alt 完整性
- 第 5 章 目录页与分页:列表页分批渲染,第二页独立成文件
- 第 6 章 sitemap:按页面清单生成,priority 按首页 1.0、栏目 0.8、正文 0.6 分档
- 第 7 章 增量构建:改一个数据文件只重建受影响的 6 个页面
# 第 2 层:片段函数只负责结构,不碰数据
def card(item):
return (
f'<a class="xy-card" href="{item["url"]}">'
f'<span class="xy-card-tag">{item["tag"]}</span>'
f'<h3>{item["title"]}</h3>'
f'<p>{item["text"]}</p>'
'</a>'
)
# 第 4 层:渲染后立即检查,问题在构建期暴露
for page in pages:
assert page["title"] not in seen_titles, page["path"]
seen_titles.add(page["title"])
参数与交付
| 项目 | 内容 |
|---|---|
| 难度 | 中等,会写 Python 函数即可 |
| 章节 | 8 章,含完整脚本、示例数据与检查脚本 |
| 实测时长 | 7 小时(读 4 小时 + 改造成自己站点 3 小时) |
| 验证环境 | Python 3.13 / 任意静态服务器 |
| 前置知识 | 知道 HTML 转义、文件读写、列表推导 |
| 配套资源 | 640 行脚本、38 页示例数据、4 类检查脚本 |
| 更新节奏 | 每半年补一次浏览器与规范变化 |
| 阅读授权 | 单账号,可读 24 个月,可商用改造 |
三个会用到它的场合
几十页的企业站或博客
38 页量级用框架偏重,用脚本刚好。构建 2.4 秒,改一次导航只改一个列表,出版本时把整个目录丢到静态服务器就能跑。
要交一份可交付的静态包给客户
客户环境常常不能装 Node。零依赖脚本在任何有 Python 的机器上都能跑,交付包里带脚本与数据,客户改文案后自己重新构建即可。
给站群做统一骨架
同一套脚本换一份数据,就能生成结构一致、内容不同的站点。第 7 章的增量构建让改一个站的数据不影响其它站。
和常见讲法差在哪
- 脚本完整给出,640 行没有省略号。多数教程只给 80 行的核心片段,剩下的目录页、分页、sitemap 让你自己补。
- 第 4 层的检查脚本是重点:渲染完立刻跑链接与标题检查,问题在构建期暴露,不会等到上线才发现死链。
- 给了 38 页的真实数据做参照,包括 15 条带日期的动态页与 4 个目录页,可直接替换成自己的内容。
交付周期与阅读节奏
开通 10 分钟内可读,脚本与示例数据随页面下载。8 章建议两天,第一天读 1—4 章并跑通示例,第二天读 5—8 章改造成自己的站点。中位耗时 7 小时,改造 3 小时左右,主要花在把旧页面搬进数据 dict 上。
服务条款
14 天内可退。脚本可商用改造,无需署名,但不得原样转售。构建逻辑若因 Python 版本变化失效,20 个工作日内补丁;章节内标注的耗时基于 Python 3.13 与一台 4 核笔记本,你的机器可能有差异。
选型建议
页面少于 10 个,直接手写 HTML 更快,不必上脚本。页面 20 到 200 个、且导航与页脚需要统一的项目最适合。超过 300 页则要考虑增量与并行,第 7 章的增量构建能撑到 200 页左右,再多要改成分片渲染。
读完常见的问题
- 需要会前端框架吗?
- 不需要。脚本只输出 HTML 字符串,写的是普通标签与类名,会 HTML 就能改模板。
- 能生成 RSS 吗?
- 第 6 章末尾附了一段 RSS 生成代码,40 行,可按需加。
- 图片要自己压吗?
- 脚本不带图片处理。文中给了一条外部命令做批量压缩与转格式,跑一次处理完整站图片。