编程 Pelican 4.12 升级前要核对的事：Python 3.11 成硬门槛，Pygments 上界放到 2.20

2026-10-29 00:04:41

Pelican 4.12 升级前要核对的事

Pelican 4.12.0 于 2026-04-20 发布。项目仍是那套 Python 静态站点生成器：Markdown / reStructuredText 写内容，Jinja2 主题渲染，输出 Atom/RSS feed，带代码高亮、内容缓存与增量写出，插件走 pelican-plugins 生态。

仓库：https://github.com/getpelican/pelican
文档：https://docs.getpelican.com/en/latest/
Release：https://github.com/getpelican/pelican/releases/tag/4.12.0
PyPI：https://pypi.org/project/pelican/

一、运行时与依赖下限

Python 门槛提到了 3.11，3.14 已进测试矩阵（3.8 在 4.11.0 就去掉了）。

requires-python = ">=3.11"
license = "AGPLv3"

4.12.0 的 pyproject.toml 依赖：

blinker>=1.7.0
docutils>=0.22.0
feedgenerator>=2.1.0
jinja2>=3.1.2
ordered-set>=4.1.0
pygments>=2.16.1,<2.20.0
python-dateutil>=2.8.2
rich>=13.6.0
unidecode>=1.3.7
watchfiles>=0.21.0
tzdata            # 仅 win32

两处要单独看：

Docutils 0.22+：reStructuredText 用户会遇到更严格的解析器，html5 writer 成为默认。老 .rst 里那些将就能过的标记，升级后可能直接报错。
Sphinx 9.0+：只在构建 Pelican 自身文档时相关，不影响站点构建。

二、安装与常用命令

安装文档这次整体重写过（#3549），官方给出了 pipx 与 uv 两条路：

pipx install pelican
# 或
uv tool install pelican

插件不随包分发，pelican-plugins 里的东西继续写进 requirements 文件里固定住。

日常命令没变：

pelican-quickstart                # 生成骨架
pelican -l -r                     # 本地监听 + 自动重载
pelican content -s publishconf.py # 生产构建

配置仍是 pelicanconf.py / publishconf.py 分流：本地开发常把 SITEURL 留空并置 RELATIVE_URLS = True，publishconf.py 里设 SITEURL 并开 feed，DELETE_OUTPUT_DIRECTORY 控制是否清空重建。

三、会改变输出结果的行为变更

这几条是升级后最容易在 CI diff 里冒出来的。

FEED_DOMAIN 回退到 SITEURL（#3477）。以前 FEED_DOMAIN 未设置会触发 feed 警告并可能生成相对/错误的 feed 链接；现在未设置时直接取 SITEURL。同时 #3544 让「已显式设置 FEED_DOMAIN」的情况不再打印 feed 警告。如果你的构建脚本靠那条警告判断配置缺失，逻辑要改。

category/tag feed 标题改用 slug（#3569）。有下游程序解析 feed 标题文本的，先确认。

文章摘要里不再包含 TOC 元素（#3512）。索引模板若依赖 summary 里自带一小段目录，那段会消失。

被禁用输出的 category 恢复产出（#3589）。之前这类分类下的文章会静默缺失，升级后它们重新出现在输出目录里——检查一下多出来的页面是不是你想要的。

IGNORE_FILES 默认递归忽略隐藏文件（#3441，4.11.0 起）。默认值现在还会叠加 watchfiles.DefaultFilter 的默认过滤规则。把 .well-known/acme-challenge 这类点路径放在 content/ 下当静态文件用的，默认会被跳过，必须自己覆盖 IGNORE_FILES。

SOURCE_DATE_EPOCH 决定「当前年份」（#3430，4.11.0 起）。模板页脚里的年份改成从该环境变量取，可复现构建不会再被打上构建当天的年份。

Pygments 上界从 <2.19 放宽到 <2.20.0。也就是说 2.19.x 现在会被装进来。如果你之前手动 pin 了 pygments==2.18.x，全新安装后高亮输出可能变化，CI 里会出现大片颜色 class 的 diff。

四、模板与主题

notmyidea 模板加入暗色模式（#3490）。
Simple 主题支持 CSS_FILE setting（#3555），并改进了模板继承结构（#3570）；4.11.0 还给 Simple 的 base 模板补了更多 block（#3405）。自己 override 过 Simple 模板的，升级后要重新对一遍 block 名。
4.11.0 新增可选择性关闭 Typogrify 过滤器的 setting（#3439），配合 Typogrify 2.1+ 的下限使用。

五、修复项

docserve() 任务里 livereload 的 import 修正（#3583）。
Windows 上的 JavaScript MIME 检测修正（#3594）。
过滤后的日志不再抛异常（#3547）。
文档里指向单个 setting 的锚点链接修好（#3458）。
GitHub Pages workflow 增强（#3452、#3529）。

六、从 4.10.x 直接跳到 4.12 的额外检查

4.11.0（2025-01-15）与 4.10.2（2024-11-27）之间还有几条会落到你头上的：

IGNORE_FILES 默认值改为忽略所有隐藏文件（4.10.2）。
SUMMARY_MAX_PARAGRAPHS 在与 SUMMARY_MAX_LENGTH 的某些组合下不再失效（4.10.2）——摘要长度可能变。
主题、内容或配置文件改动后的自动重载行为被修正（#3441）。
Typogrify 2.1+、Pygments <2.19 的下限（4.11.0）。

升级核对清单

确认 Python ≥ 3.11，CI 矩阵补上 3.14。
pipx install pelican 或 uv tool install pelican 重装，别在旧 venv 上 pip install -U 混着来。
pip-compile 一遍依赖，重点看 docutils 与 pygments 解析出的版本。
跑 pelican content -s publishconf.py，diff 输出目录，重点看 feed 链接、feed 标题、摘要内容、多出来的分类页。
检查 content/ 下是否有依赖默认 IGNORE_FILES 放行的点路径文件。
覆盖过 notmyidea / Simple 模板的，对照 4.12 的模板重校一遍。
需要可复现构建的，把 SOURCE_DATE_EPOCH 写进构建环境。