版本概览

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

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

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

性能优化

• 首页和列表页默认只向客户端发送文章摘要字段,减少 __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,并通过运行态脚本验证核心链接映射逻辑。

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

NotionNext v4.9.5.2

本版本重点聚焦三件事:性能基线建立、运行时稳定性修复、协作规范完善。
适合准备长期维护或扩展新主题的团队升级。

亮点更新

1) 全主题性能基线(生产模式)

• 新增全主题审计命令:yarn perf:audit:themes
• 审计结果落库并可追踪:
  • docs/performance/theme-audit-latest.md
  • docs/performance/theme-audit-latest.json
• 在 DEVELOPMENT.md 新增"新主题性能准入"流程,后续主题开发可按统一标准验收(LCP/CLS/SEO 等)。

2) 运行时稳定性修复

• 修复 Invalid hook call 等关键运行时问题。
• 修复部分主题中的 React 警告:
  • 列表 key 警告
  • 非法 DOM prop 透传警告
  • defaultProps 兼容性警告
• 修复 Mermaid 渲染相关回归与深色模式视觉一致性问题。

3) 低风险性能优化(高性价比)

• 优化构建与运行热路径,降低不必要 CPU 开销。
• 首页预览数据读取策略优化(并发与范围控制)。
• 优化缓存热路径判断逻辑。
• 减少不必要重依赖开销,补充主题预览图 WebP 资源流程。
• 增强图片加载降级策略,提升复杂图源场景稳定性。

4) 文档与协作体验升级

• 项目文档导航补齐双语入口(中文/英文)。
• 新增中文贡献文档:CONTRIBUTING.zh-CN.md
• package.json 脚本在开发文档中补齐用途说明,方便新贡献者快速上手。
• 版本号更新至 4.9.5.2。

What's Changed

• chore(theme-preview): add claude preview image by @tangly1024 in #3974
• chore(ci): align Yarn version for Cloudflare builds by @tangly1024 in #3976
• chore(ci): standardize Yarn-first developer workflow by @tangly1024 in #3979
• chore(config): tune Node engine range and root guidance by @tangly1024 in #3980
• feat: 优化代码折叠逻辑,引入行数阈值检测与极简 S1 UI by @RHZHZ in #3767
• perf: 全主题性能基线、运行时修复与低风险优化 by @tangly1024 in #3981

New Contributors

• @RHZHZ made their first contribution in #3767

Full Changelog: v4.9.5.1...v4.9.5.2

Contributors

• @tangly1024
• @RHZHZ

NotionNext v4.9.5.1

本版本是一次较大范围的迭代,重点覆盖 新主题能力(Fuwari / Claude)、渲染与兼容性稳定性、站点生成链路健壮性 与 工程流程完善。
相较 v4.9.4.4,本版本在主题体验统一性、跨场景兼容性与维护可控性方面有明显提升。

升级亮点总览

• ✅ 完成 Fuwari 主题迁移与多轮体验打磨
• ✅ 引入 Claude 主题(增量接入,不破坏现有主题体系)
• ✅ 修复 Mermaid / Prism / Gitbook 深色模式 等高频反馈问题
• ✅ 修复 站点封面、Sitemap、RSS 等关键基础能力
• ✅ 增强 Issue 响应自动化 与评论系统兼容性
• ✅ 版本升级至 4.9.5.1

详细变更

1. Fuwari 主题(迁移 + 交互完善)

1.1 主题迁移与发布

• 完成 Fuwari 主题在 NotionNext 的适配迁移,建立主题基础布局与视觉体系。
• 形成可持续迭代的配置与组件组织方式,为后续主题共性能力复用打基础。
  • PR: #3961

1.2 移动端与导航交互优化

• 优化移动端顶部栏布局,提升小屏设备可读性与触达效率。
• 新增目录悬浮抽屉交互,改善文章内快速定位体验。
  • PR: #3962

1.3 菜单与归档链路修复

• 修复二级菜单交互问题(显示/点击路径更稳定)。
• 优化归档跳转参数继承逻辑,减少路由切换时的状态丢失。
  • PR: #3963

1.4 视觉与可用性细节

• 调整主题调色板行为,减少切换时体验不一致。
• 优化 analytics i18n 文案与 Hero 区域信息清晰度。
  • PR: #3964

1.5 收尾与稳定性修正

• 完成 Fuwari 阶段性收尾,补齐 TechGrow 模态行为问题。
• 稳定 Contact Card 翻转表现,减少镜像/背面可读性问题。
  • PR: #3967
  • PR: #3971

2. Claude 主题引入(增量接入)

• 新增 Claude 主题能力,采用增量接入策略,尽量避免影响既有主题。
• 覆盖主题必要组件与数据链路说明,便于后续维护和二次开发。
  • PR: #3789

注:Claude 主题后续还在相关 PR 中持续补充稳定性/安全性修复(例如菜单回退、刷新链路安全、README 渲染边界、文档整理等)。

3. Mermaid / Prism / Gitbook 相关稳定性

3.1 Mermaid 渲染生命周期修复

• 修复主题切换后 Mermaid 需要强刷才能渲染的问题。
• 改进多容器场景下 Mermaid 的扫描与绑定策略,提升动态页面稳定性。

3.2 Prism 作用域与主题兼容

• 调整 Prism/Mermaid 的作用域定位逻辑,降低不同主题结构差异导致的误匹配或漏匹配。

3.3 Gitbook 深色模式配色协调

• 优化移动端底部导航、抽屉层、目录与文章列表在 dark 模式下的配色一致性与可读性。
  • PR: #3972
  • PR: #3973

4. 核心能力修复(全站层)

4.1 首页封面回退逻辑修复

• 修复数据库根页面场景下首页封面回退策略,补齐对 page_cover 优先链路的支持。
  • PR: #3825

4.2 Proxio 导航回退修复

• 在 CUSTOM_MENU 开启但自定义菜单为空时,保留默认导航回退,避免菜单整体消失。
  • PR: #3807

4.3 Sitemap 生成健壮性提升

• 跳过外部 slug,避免无效 URL 混入站点地图。
• 增加非法日期兜底,防止 sitemap 输出异常时间值。
  • PR: #3806

4.4 RSS 404 问题修复

• 修复 RSS 页面生成/访问失败导致 404 的问题,增强 Notion 数据格式兼容。
  • PR: #3804

5. 工程化与平台集成

5.1 自动化流程

• 新增 Issue Response Bot 工作流,提高 issue 首次响应效率与规范化程度。
  • PR: #3965

5.2 评论系统集成修复

• 修复 Giscus Discussion 集成参数缺失(data-category、data-strict、crossOrigin)。
  • PR: #3966

5.3 仓库清理与发布准备

• 优化 .gitignore(包括本地临时目录与测试产物策略)。
• 回填本地开发缓存与部分主题 UX 变更,减少遗落差异。
• 修复 SEO 中无效字体 preload。
  • PR: #3968
  • PR: #3969
  • PR: #3970

6. 版本变更

• 版本号从 4.9.5.0 升级至 4.9.5.1。
  • PR: #3975

PR 列表(按时间线)

• #3961 feat(theme): 完成 fuwari 主题迁移并发布 v4.9.5.0
• #3962 fix(fuwari): 优化移动端顶栏布局并新增目录悬浮抽屉
• #3963 fix(fuwari): 修复二级菜单交互并优化归档跳转参数继承
• #3964 fix(fuwari): refine palette behavior, analytics i18n, and hero clarity
• #3967 feat(fuwari): finalize theme work and fix TechGrow modal behavior
• #3965 Add automated Issue Response Bot GitHub Actions workflow
• #3966 Fix Giscus GitHub Discussion integration
• #3968 chore(gitignore): ignore local .tmp workspace directory
• #3969 chore: backfill missed local dev cache and fuwari UX updates
• #3970 fix(seo): remove invalid inter-var preload
• #3971 fix(fuwari): stabilize contact card flip and prism scoping
• #3972 fix(prism,gitbook): stabilize mermaid lifecycle and dark mode palette
• #3973 fix(prism,gitbook): stabilize mermaid lifecycle and dark mode palette
• #3825 Fix homepage site cover fallback for database root page
• #3807 fix(proxio): keep fallback nav when custom menu is empty
• #3806 fix(sitemap): skip external slugs and guard invalid dates
• #3804 修复RSS页404报错
• #3789 Claude 主题
• #3975 chore(release): bump version to 4.9.5.1

New Contributors

感谢以下首次贡献者:

• @Copilot in #3965
• @yunhe-dev in #3825
• @qianzhu18 in #3807
• @lyizhuo in #3804
• @HiderX in #3789

Full Changelog: v4.9.4.4...v4.9.5.1

Contributors

• @yunhe-dev
• @HiderX
• @lyizhuo
• @qianzhu18

NotionNext v4.9.4.4

这个版本重点围绕 稳定性、兼容性与协作体验:修复 Notion 数据结构兼容问题、增强多 Worker 构建稳定性、补齐外链与 TechGrow 行为一致性,并补充了更完善的开源协作文档。

✨ Highlights

• Notion 兼容性增强

  • 修复新版 Notion heading 类型下的 TOC 解析异常
  • 修复 Notion data source/schema 解析与页面列表合并问题
  • 修复读取 Notion 列表时的数据窜读问题

• 构建稳定性优化(并发场景)

  • 基于 #3906 的增强,补强 export 阶段 block prefetch 在多 Worker 环境下的协调行为,降低重复预热与超时退化风险

• 安全与部署

  • 锁定 form-data resolution 到 ^4.0.4
  • 最小化引入 Netlify Next.js 兼容配置

• 体验改进

  • 修复 heo 主题翻转卡片悬停状态异常
  • Notion 外链默认新标签页打开,并增加同源保护
  • 增强 TechGrow 兼容性,替代 OpenWrite 公众号解锁方案
  • 新增全局置顶标签排序(仅重排置顶子集,按最近更新时间倒序)

• 文档与协作

  • 完善开源协作文档体系,并升级版本到 4.9.4.4

📦 What's Changed

• Fix: 读取Notion列表窜数据 by @tangly1024 in #3932
• Fix TOC parsing for newer Notion heading types. by @tangly1024 in #3946
• 并发编译优化:基于 #3906 补强 export 阶段 block prefetch 的多 Worker 协调 by @88lin in #3919
• security: pin form-data resolution to ^4.0.4 by @tangly1024 in #3952
• Fix Notion data source schema parsing and page list merging. by @tangly1024 in #3953
• fix: 修复 heo 主题交流频道翻转卡片悬停状态异常 by @88lin in #3871
• fix(notion): open external article links in new tabs with same-origin safeguard by @tangly1024 in #3954
• chore(netlify): 最小化引入 Netlify Next.js 兼容配置 by @tangly1024 in #3955
• 增强 TechGrow 兼容性:替代OpenWrite公众号解锁方案 by @tangly1024 in #3956
• feat: 新增全局置顶标签排序(仅重排置顶子集,按最近更新时间倒序) by @tangly1024 in #3959
• docs: 完善开源协作文档体系并升级版本到 4.9.4.4 by @tangly1024 in #3960

🙌 New Contributors

• @88lin made their first contribution in #3919

Full Changelog: v4.9.4.2...v4.9.4.4

Contributors

• @tangly1024
• @88lin

What's Changed

• feat(theme): 完成 fuwari 主题迁移并发布 v4.9.5.0 by @tangly1024 in #3961

Full Changelog: v4.9.4.4...v4,9.5.0

Contributors

• @tangly1024

What's Changed

• Normalize build and compilation speed by @tangly1024 in #3898
• fixbuild by @tangly1024 in #3899
• 构建模式调整 by @tangly1024 in #3904

Full Changelog: v4.9.4.1...v4.9.4.2

Contributors

• @tangly1024

What's Changed

• 临时处理 429 Too Many Request 问题
• 升级notion-utils-7.10.0 by @tangly1024 in #3887
• Release/4.9.4.1 by @tangly1024 in #3897

Full Changelog: v4.9.4...v4.9.4.1

Contributors

• @tangly1024