v4.10.8

v4.10.8

本版本新增 Cloudflare Worker 版 Notion 图片反代方案，用于把 Notion 素材统一走站长自己的 CDN 域名缓存。

Notion 图片反代

• 新增 cloudflare/notion-image-proxy 最小 Worker 工程。
• 示例生产域名切换为 cdn.tangly1024.com。
• 支持 Notion /image/ 签名跳转链路，并使用 Worker Cache API 显式缓存响应。
• 重复访问同一图片可通过 CF-Cache-Status: HIT 与 X-Notion-Image-Proxy-Cache: HIT 验证命中。
• NotionNext 接入方式保持简单：配置 NEXT_PUBLIC_NOTION_HOST=https://你的CDN域名。

文档

• 新增 VitePress 教程：docs/user-guide/deploy/notion-image-proxy.md。
• 教程覆盖 Cloudflare API Token 权限、Custom Domain 不能带路径、浏览器内存缓存误判、prod-files-secure 图片签名机制、动态部署和静态导出兼容性。
• 部署侧边栏和文章索引新增「Notion 图片反代」入口。

验证

• node --check cloudflare/notion-image-proxy/worker.mjs
• yarn docs:site:build
• git diff --check
• curl 连续请求真实 Notion 图片，第二次返回 CF-Cache-Status: HIT

v4.10.7

4.10.7 发布要点

本版本将主题颜色定制从 Tailwind 类名覆盖，过渡到主题语义色变量与调色板方案。

主题调色板

• 全局主题工具新增当前主题调色板，展示每个主题可覆盖的色号变量、CSS 变量名、默认色值和复制入口。
• 25 个内置主题均已接入 *_COLOR_* / palette 元数据，切换主题后即可查看当前主题可配置色号。
• Fuwari 保留原有色相模型，调色板对 FUWARI_THEME_COLOR_HUE 做 hue/hex 兼容，避免破坏现有配置。
• Endspace、Heo、Claude 等多色主题提供背景、文字、强调色、边框等变量；轻量主题保持基础色板。

配置与兼容

• 用户可在 Notion Config 表、环境变量或主题 config.js 中覆盖主题色号。
• 保留既有 TailwindCSS 与旧配置渲染路径，不要求用户立即迁移。
• 补充主题控制台用户文档、主题迁移指南、主题色 token roadmap 和各主题配置说明。

相关变更

• #4280
• #4285
• #3393

v4.10.6

4.10.6

This release collects the fixes and documentation updates merged after v4.10.5.

Highlights

• Improved the NotionComments experience.
• Fixed Endspace custom menu icons and submenu expansion.
• Fixed Hexo AOS refresh behavior.
• Fixed GitBook jump-to-top alignment.
• Fixed Starter theme defaults and feature button text.
• Fixed Magzine first-viewport loading stability.
• Removed incorrect SEO theme microdata.
• Preserved synced block children in notice content.
• Avoided overwriting custom robots.txt.
• Stabilized docs chat message handling, fallback behavior, legacy embeds, and version display.
• Fixed hidden posts being counted in tag totals.
• Added and clarified AI assistant, Cloudflare Pages, bug contribution, and theme switching docs.

Commit range

v4.10.5...d652f6c32e25bafe4b1d3391159872da55629602

Contributors

Thanks to @tangly1024, @QianZhu, @githubdudu, and @jk9112605.

v4.10.5

4.10.5 发布要点

本版本新增基于 Notion 数据库的 NotionComments 评论插件，并合入 v4.10.4 之后主线上的主题修复、Notion 渲染增强、复制权限配置、SEO 和依赖更新。

NotionComments 评论插件

• 新增 NEXT_PUBLIC_COMMENT_NOTION_ENABLE 评论开关，可与 Waline、Giscus、Valine、GitTalk、Utterance、Cusdis、Twikoo 等评论插件并存，通过文章底部评论区 Tab 切换体验。
• 新增 /api/notion-comments 动态接口，评论数据写入用户自己的 Notion 数据库，支持文章维度查询、发表评论、回复评论、分页加载和失败重试。
• 新增评论区交互界面：加载中、空状态、错误重试、回复输入、收起回复、加载更多等基础状态都已覆盖。
• 新增 NotionComments 使用教程，包含 Notion Integration 创建、数据库字段配置、环境变量、部署方式、常见问题、使用效果截图，以及“独立评论数据库”和“Notion 页面原生评论”两种方案的取舍说明。
• 新增会员评论路线图文档，记录未来会员体系和评论能力继续结合 Notion 数据的可选方向。

主线功能与修复

• 支持文章级自定义版权模式，并补充 CAN_COPY 复制权限配置文档和侧边栏入口。
• 改进 SEO canonical metadata，减少错误 canonical 地址对搜索收录的影响。
• 支持 Notion Heading 4 渲染。
• 支持应用 Notion Collection View 的排序规则。
• 修复分类和标签静态路径生成的保护逻辑。
• 同步 Endspace 主题更新。
• 修复 Claude 主题侧栏在 Adsense 场景下的高度问题。
• 修复 Fuwari 固定主题色不生效问题。
• 修复 Magzine 主题文章标签换行问题。
• 为分享按钮和右侧浮动区域补充鼠标悬停提示。

依赖与工作流更新

• form-data 从 4.0.5 升级到 4.0.6。
• @babel/core 从 7.28.3 升级到 7.29.7。
• axios 从 1.17.0 升级到 1.18.1。
• @vercel/functions 从 3.6.2 升级到 3.7.5。
• actions/checkout 从 4 升级到 7。
• docker/metadata-action 从 5 升级到 6。

升级说明

• 如需启用 NotionComments，需要新增：
  • NEXT_PUBLIC_COMMENT_NOTION_ENABLE=true
  • NOTION_COMMENT_DATABASE_ID=你的评论数据库 ID
  • NOTION_TOKEN=你的 Notion Integration Token
• NotionComments 依赖服务端 API Route，只支持 Vercel、Netlify、Node.js Server、Docker 等动态部署方式；使用 yarn export / 纯静态导出的站点不支持该插件。
• NOTION_TOKEN 是敏感凭据，只应保存在服务端环境变量中，不要提交到仓库，也不要暴露在公开截图或前端配置里。

自 v4.10.4 以来的提交

• feat: add Notion database comments plugin
• docs: add optional membership comments roadmap
• fix(endspace): sync upstream theme updates
• fix: improve SEO canonical metadata (#4248)
• feat: support custom article copyright mode
• fix(claude): keep sidebar height with adsense (#4247)
• fix: guard category/tag static paths
• docs: explain adding CAN_COPY in Notion
• docs: expose copy permission guide in sidebar
• docs: add copy permission guide to config index
• feat: support per-post copy permissions
• fix(fuwari): honor fixed theme hue (#4243)
• fix(magzine): keep post tags on one line
• docs: fix post list style config comment (#4242)
• fix: support Notion heading 4 (#4241)
• fix: apply Notion collection view sorts (#4240)
• chore(share buttons): add tips for mouse hover (#4212)
• chore(right float area): add tips (#4213)
• chore: bump form-data from 4.0.5 to 4.0.6 (#4204)
• chore: bump @babel/core from 7.28.3 to 7.29.7 (#4211)
• chore: bump axios from 1.17.0 to 1.18.1 (#4222)
• chore: bump docker/metadata-action from 5 to 6 (#4228)
• chore: bump actions/checkout from 4 to 7 (#4229)
• chore: bump @vercel/functions from 3.6.2 to 3.7.5 (#4238)

验证

• jest __tests__/lib/plugins/notionComments.test.js --runInBand：通过。
• next lint --file components/NotionComments.js --file lib/plugins/notionComments.js --file __tests__/lib/plugins/notionComments.test.js：通过。
• git diff --check：通过。
• yarn docs:site:build：通过。

Full commit range (v4.10.4..v4.10.5)

ext 8f34b9e2 docs: complete v4.10.5 release notes 396fbe83 feat: add Notion database comments plugin 4bd425e9 docs: add optional membership comments roadmap 8f7aefad fix(endspace): sync upstream theme updates 0f064a4c fix: improve SEO canonical metadata (#4248) 2e781454 feat: support custom article copyright mode 8195d096 fix(claude): keep sidebar height with adsense (#4247) 8edf62df fix: guard category/tag static paths ab0ed941 docs: explain adding CAN_COPY in Notion 4db97ebe docs: expose copy permission guide in sidebar 57bb0ef1 docs: add copy permission guide to config index a93e7ebb feat: support per-post copy permissions 62809501 fix(fuwari): honor fixed theme hue (#4243) ad33c3ae Merge branch 'codex/fix-post-list-style-comment' 3fb7fbf1 fix(magzine): keep post tags on one line 7c7956fc docs: fix post list style config comment (#4242) d4e32518 docs: fix post list style config comment 487ec9e4 fix: support Notion heading 4 (#4241) c023e79a fix: apply Notion collection view sorts (#4240) 1a3f9324 chore(share buttons): add tips for mouse hover (#4212) 58d86b53 chore(right float area): add tips (#4213) 9cf7d24f chore: bump form-data from 4.0.5 to 4.0.6 (#4204) bf5798b1 chore: bump @babel/core from 7.28.3 to 7.29.7 (#4211) 57a1b143 chore: bump axios from 1.17.0 to 1.18.1 (#4222) b1e3442c chore: bump docker/metadata-action from 5 to 6 (#4228) 628971e7 chore: bump actions/checkout from 4 to 7 (#4229) 559a5541 chore: bump @vercel/functions from 3.6.2 to 3.7.5 (#4238)

v4.10.4

4.10.4

本版本补齐 Notion 2026 年新增 HTML Block 的渲染支持，让 Notion AI 生成或用户上传的 .html 小工具可以在 NotionNext 文章中直接展示。

更新内容

• 支持 Notion HTML Block 在 API 中返回的 embed + html_artifact 数据结构。
• 为 HTML artifact 附件补齐 Notion signed URL，并保留原始 attachment: source。
• 服务端读取 HTML artifact 内容，再通过 sandbox iframe srcDoc 渲染，避免 Notion 附件的下载响应头和 CSP 导致 iframe 空白。
• 普通外部网页 Embed 仍按原有 iframe 方式渲染。
• 限制单个 HTML artifact 最大 512KB，避免页面数据过大。
• 更新版本号、最新 changelog 和示例文章功能说明。

验证

• git diff --check
• yarn lint --file components/NotionPage.js --file lib/db/notion/getPostBlocks.js --file lib/db/notion/getNotionAPI.js
• node -e "const p=require('./package.json'); if (p.version !== '4.10.4') process.exit(1)"
• yarn docs:site:build

v4.10.3

4.10.3 发布要点

本版本重点优化 Magzine 主题、字体资源、构建缓存和 Notion 数据过滤，并合入社区站数据库、视图筛选、Heo / Fuwari / Hexo / Matery 主题体验与依赖安全更新。

性能与资源加载

• 优化 Magzine 首页首屏图片加载策略，减少 LCP 图片延迟。
• 调整 Magzine 首页图片、广告位与文章卡片布局，降低图片、广告和卡片内容加载时的布局抖动。
• Font Awesome 样式改为延后加载，并在用户有交互意图后再加载，减少首屏阻塞。
• 预留 Font Awesome 图标布局空间，修复延迟加载期间图标可见性和页面跳动问题。
• 将 Font Awesome 字体文件改为本地自托管，减少第三方字体 CDN 依赖。
• Web Font 仅在配置启用时加载，未配置自定义字体的站点不再请求额外字体资源。

Notion 数据与构建稳定性

• 稳定本地构建缓存文件锁，降低并发构建或重复读取缓存时的异常风险。
• 优化 filtered collection 数据处理，减少无关 Notion collection 数据进入页面数据。
• 保留空的 selected view 结果，避免空集合视图被误判为缺失数据。
• 增加 typed collection helper，统一集合数据读取路径。

主题与配置

• Fuwari 主题首次渲染时正确应用主题色相，并补充主题切换稳定性调整。
• Heo 信息卡 greeting 逻辑归一化，避免不同配置路径显示不一致。
• Hexo / Matery 主题新增 greeting words speed 配置，可控制首页问候语切换速度。
• 新增社区站数据库模板文档，补充 Notion 社区站点搭建入口。

文档与部署

• 文档站首页和导航加入最近更新提示能力，方便维护者发现新 changelog 与重要文档更新。
• 更新 Cloudflare Pages V3 build image 迁移说明。
• 更新开发者首页、愿景路线图与性能优化计划，记录本轮性能优化和后续维护方向。

依赖更新

• axios 升级到 1.17.0。
• @vercel/functions 升级到 3.6.2。
• ioredis 升级到 5.11.1。
• @supabase/supabase-js 升级到 2.107.0。

参与者

• @tangly1024：33 个提交。
• @qianzhu / Lucien：6 个提交。
• @dependabot：4 个提交。
• @88lin：1 个提交。
• @expoli：1 个提交。
• @githubdudu：1 个提交。

提交范围

从 v4.10.2 到 v4.10.3：

• 5a1017a7 fix: filter embedded Notion collection views
• 6ec30f99 chore(release): bump package.json to 4.10.1
• 9c793e3c fix: handle sync_block with content ID array
• 782a35bf fix: render quote blocks without properties.title
• 6b24adc9 fix: respect view-level filters in database page resolution
• f837e3d9 fix: apply Fuwari theme hue on initial render
• 1a6b2263 fix: preserve giscus oauth callback token
• 8f685096 docs: surface changelog unread updates
• 1aeac547 merge: release v4.10.2 hotfix
• ee1043ee fix: limit docs unread dots to sidebar
• a0c9970c fix: mark latest docs unread in sidebar
• 2eee510d fix: record docs reads for every route
• 07ccff5b fix: render sidebar unread dots as nodes
• 3815bda6 fix: keep sidebar unread leaf dots visible
• 302feebb fix: normalize Heo infocard greetings
• 5252770e refactor: add typed collection helpers
• 61b8c774 docs: add community site database template
• 4fb658be fix: preserve empty selected view results
• 88e03cc1 chore: bump @supabase/supabase-js to 2.107.0
• e747d117 chore: bump ioredis to 5.11.1
• 8e11d730 chore: bump @vercel/functions to 3.6.2
• 186b3e3a chore: bump axios to 1.17.0
• 9922643f Optimize Font Awesome stylesheet loading
• 3abb4a83 Merge Font Awesome loading optimization
• 35f332d5 Improve magzine homepage performance
• 6ccd2b86 Merge magzine homepage performance improvements
• 560d04e2 Optimize magzine LCP image loading
• c9373041 Merge magzine LCP image optimization
• 1e34875b Stabilize build cache locks and filtered collection data
• 7d431f12 Merge build cache stability updates
• cb4c065d docs: add Cloudflare Pages V3 build image migration
• 941cf310 Improve magzine image and ad layout stability
• e3d91b9e Merge magzine image layout stability
• a9525fff Defer Font Awesome from critical path
• f96fecd5 Merge Font Awesome critical path deferral
• 2362c9c2 Load web fonts only when configured
• 8d783e33 Merge deferred web font loading
• ff2c5073 Load Font Awesome after user intent
• 8da1cf29 Merge Font Awesome intent loader
• 1e4e2de4 Reserve Font Awesome icon layout
• 33ad83bf Merge Font Awesome layout reservation
• 2a1dda67 Fix delayed Font Awesome visibility
• ad5e32b2 Merge Font Awesome visibility fix
• df71ae22 Self-host Font Awesome for menu icons
• 256a2363 Merge self-hosted Font Awesome performance fix
• 512524a7 feat: add configurable greeting words speed

适用场景

• 使用 Magzine、Fuwari、Heo、Hexo 或 Matery 主题的站点。
• 希望减少 Font Awesome / Web Font 对首屏渲染影响的站点。
• 使用 Notion collection view、Cloudflare Pages 或依赖构建缓存的站点。

升级说明

• 正常升级无需新增环境变量。
• 如果站点依赖 Font Awesome 图标，请升级后确认图标显示正常。
• 如果使用自定义 Web Font，请确认相关字体配置仍按预期启用。
• 如果使用 Hexo / Matery 主题，可按需配置 greeting words speed。

完整文档：docs/user-guide/changelog/latest.md

v4.10.2

版本概览

v4.10.2 是一次面向构建效率、Notion 数据兼容性和评论登录体验的小版本发布。重点是让未更新过的 Notion 文章在后续构建中复用正文缓存，显著减少 Notion 页面正文重复拉取；同时修复 Giscus OAuth 回跳后仍提示登录的问题。

本版本已包含 Vercel 部署 type-check 修复：fetchNotionPageBlocks 的 from 参数类型已放宽为 string | undefined，避免 lib/site/adapters/notion/notion.fetcher.ts 在生产构建中报错。

本轮发布窗口也补充记录了 4.10.1 之后主线上的多项修复，包括嵌入式 collection view 过滤、sync_block 兼容、quote block 渲染、数据库视图筛选和 Fuwari 主题色相初始化等。

主要改动

构建性能：增量 Notion 正文缓存

• 新增版本化 Notion 页面正文缓存：缓存键由 page_block_<pageId> 扩展为 page_block_<pageId>_<lastEditedTimestamp>。
• 每次构建仍重新拉取 Notion 数据库索引，用于发现新文章、删除/隐藏文章、slug 变化和 last_edited_time 变化。
• 如果文章 lastEditedDate 未变化，预热和页面渲染会直接命中上次构建缓存，不再重复请求 Notion 页面正文。
• prefetchAllBlockMaps 改为优先读取版本化正文缓存，缓存命中时跳过 fetchNotionPageBlocks。
• 单篇文章页、公告页和全文搜索统一使用版本化正文缓存，避免预热、渲染、搜索三处缓存键不一致。
• 构建启动清理策略调整为保留版本化正文缓存，只清理数据库索引、静态路径、构建 session 等临时缓存。
• 新增 NOTION_BUILD_CACHE_PURGE_DATA=true，当怀疑缓存损坏时可手动强制清空持久 Notion 数据缓存。

Vercel 构建修复

• 修复 fetchNotionPageBlocks(pageId, from) 在 TypeScript 严格检查下把 from 推断成 null | undefined 的问题。
• 修复 Vercel 构建时报错：Argument of type 'string | undefined' is not assignable to parameter of type 'null | undefined'。
• 已通过 npm run type-check 验证。

Giscus 评论登录修复

• 修复 Giscus OAuth 回跳后的 ?giscus=... token 被页面容器过早移除的问题。
• 现在回跳 token 会先交给 Giscus 脚本消费并写入 localStorage，随后再清理地址栏参数。
• 解决登录 GitHub 返回文章页后，评论框仍显示“登录后可以评论”的循环登录问题。

Notion 数据兼容性修复

• 修复嵌入式 Notion collection view 数据未过滤导致页面数据膨胀、无关集合记录泄露到页面 props 的问题。
• 修复 Notion 新结构中 sync_block 的 content ID 数组解析问题，避免同步块内容缺失。
• 修复没有 properties.title 的 quote block 渲染异常，提升 Notion 块结构兼容性。
• 修复数据库页面解析中视图筛选条件因短 ID / UUID 格式不一致而失效的问题。
• 保留并强化 collection view 过滤相关回归测试，覆盖数据库视图筛选和嵌入集合场景。

主题修复

• 修复 Fuwari 主题首次渲染时主题色相未立即应用的问题，避免初屏色彩与配置不一致。
• 修复 Magzine 主题推荐标签默认值处理，避免未配置推荐标签时推荐逻辑异常。

文档同步

• VitePress 文档的“最新版本”更新为 4.10.2。
• 同步更新用户指南、参考手册和主题目录中的当前版本标注。
• 最新版本页补充增量构建缓存的原理、适用场景和清缓存方式。
• 补充 4.10.1 之后主线同期修复范围，方便站长判断升级收益。

使用建议

• Cloudflare Pages 用户请确认 Build cache 已开启，这样 .next/cache 才能在下一次构建恢复并复用。
• 正常情况下无需配置新变量。
• 如需强制全量刷新 Notion 正文缓存，可临时设置：

NOTION_BUILD_CACHE_PURGE_DATA=true

重新部署一次后再移除该变量即可。

验证

• npm run type-check 通过。
• npx eslint lib\db\notion\getPostBlocks.js lib\site\adapters\notion\notion.fetcher.ts 通过。
• npx eslint lib\db\notion\getPostBlocks.js lib\build\prefetch.js lib\db\SiteDataApi.js pages\search\[keyword]\index.js pages\search\[keyword]\page\[page].js next.config.js 通过。
• node -e "require('./next.config.js')" 通过。
• git diff --check 通过。
• npm run docs:site:build 通过。

相关提交

• 58fa0656 fix: preserve giscus oauth callback token
• 10aae3ab release: 4.10.1 incremental notion build cache
• 4ddf7eda release: 4.10.2
• f93460fd fix: widen notion page block fetch source type
• 9c793e3c fix: handle sync_block with content ID array
• 782a35bf fix: render quote blocks without properties.title
• 6b24adc9 fix: respect view-level filters in database page resolution
• f837e3d9 fix: apply Fuwari theme hue on initial render
• e48f44e2 fix: respect magzine recommend tag default

v4.10.1

What's Changed

• Fix embedded Notion collection views so configured view filters are respected during rendering.
• Support newer Notion query2 filters, localized status group matching, and sibling filter inheritance for alternate embedded collection views.
• Fix CI follow-ups for Jest ESM mocking and the ExternalPlugins lint rule.

Verification

• Unit tests passed in GitHub Actions.
• Lint & type-check passed in GitHub Actions.
• Vercel preview and Docker build passed in GitHub Actions.

NotionNext 4.10.0

NotionNext 4.10.0

本版本是一次以多主题站点性能为核心的较大版本更新，目标是在保持现有主题、配置和插件行为不变的前提下，让站点渲染更轻、更稳、更容易验收。

性能优化

• 首页和列表页默认只向客户端发送文章摘要字段，减少 __NEXT_DATA__ 体积。
• 文章页保留渲染所需 blockMap，同时清理 Notion 内部元数据。
• latestPosts、上一篇/下一篇、推荐文章统一使用轻量摘要结构。
• 新增 yarn perf:page-data，用于在构建后检查 page-data 是否超过默认 128KB 预算。
• 批量优化多主题滚动监听，降低目录、进度条、浮动按钮等高频滚动场景的主线程压力。
• Next、Endspace、Typography 等主题完成重点性能路径优化。

修复与回归保护

• 保留 allLinkPages 链接解析路径，避免公告栏 type=notice 中指向 type=Page 的 Notion 内链重新退化为 404。
• 新增 convertInnerUrl 回归测试，覆盖 raw Notion page id 到站内 Page 链接的转换。

文档

• 更新 docs/user-guide/changelog/latest.md 到 4.10.0。
• 在 docs/user-guide/deploy/build-tuning.md 增加 page-data 预算检查说明。
• 同步用户指南、主题目录和性能阶段记录中的版本号。

验收

• yarn -s type-check 通过。
• yarn -s docs:site:build 通过。
• yarn -s build 通过。
• yarn -s perf:page-data 通过，overBudgetPages: 0。

说明：当前工作区直接运行 Jest 仍会被既有 canvas.node 原生绑定缺失问题阻塞；本次新增测试文件已通过 ESLint，并通过运行态脚本验证核心链接映射逻辑。

v4.9.5.7

NotionNext v4.9.5.7

本版本聚焦：社区/组织官网数据层、Notion 视图筛选修复、构建/CI 稳定性、依赖安全收敛与用户手册同步。

亮点更新

1. 社区官网数据层

• 新增 Member / Event 类型配置。
• getGlobalData() 输出 allMembers 与 allEvents，便于主题实现成员目录、活动列表等页面。
• 支持通过 Notion 官方 API 补充读取 Member 数据，并增加分页、状态过滤与去重。

2. Notion 数据兼容与用户可见修复

• 修复 Notion 数据库只应使用所选视图筛选结果的问题，避免其他视图隐藏条目混入。
• 修复 Font Awesome fa-x-twitter 图标加载问题。
• Endspace 主题支持自定义多级菜单。

3. 构建、CI 与发布流程

• 恢复 lint / type-check / 单测 / VitePress / Docker 检查基线。
• Docker 构建严格使用 yarn.lock；PR 构建收敛到单架构以降低耗时。
• 主分支自动版本号 workflow 改为推送维护分支，兼容受保护 main。

4. 安全与依赖

• 合并 Dependabot patch 更新：@supabase/supabase-js、@clerk/localizations、开发依赖组等。
• 收敛 qs、tmp、js-cookie、uuid、lodash、picomatch、flatted、esbuild 等传递依赖到修复版本。

5. 文档

• docs/user-guide/changelog/latest.md 已同步 4.9.5.7 更新记录。
• user guide 当前主线版本说明同步到 4.9.5.7。

相关问题

• Closes #4035
• Fixes #4039
• Fixes #3940
• Fixes #3984

Full Changelog: v4.9.5.2...v4.9.5.7