个人博客改造全记录：NotionNext 升级踩坑、字段设计与 SEO 优化

type

Post

status

Published

date

May 7, 2026

slug

notionnext-renovation-guide

summary

NotionNext 升级踩坑全记录：主题失效、文章不显示的根因与修复，Notion 数据库字段设计指南，及 SEO 100分优化建议

一、背景

koffuxu.com 是一个基于 NotionNext 框架、部署在 Vercel 上的个人博客，以 Notion 数据库作为 CMS 内容管理后台。

2026 年 4 月 14 日，将 blog 分支与上游 main 分支合并，经历了一次从旧版本到 4.9.4.2 的大版本升级。升级后随即出现两个问题：

主题没有切换：Vercel 重新部署后，配置的 hexo 主题未生效，仍然显示旧主题样式

新文章不显示：首页文章列表停留在 2023 年的旧内容，新增的文章完全看不到

二、问题排查与修复

问题一：主题切换后不生效

根本原因：webpack alias 在构建时写死

next.config.js 第 1 行：

主题名通过 webpack alias @theme-components 在构建阶段确定，不是运行时读取。即使在 Vercel 添加了环境变量 NEXT_PUBLIC_THEME=hexo，如果构建缓存没有失效，新的 webpack alias 不会生效。

修复方法：在 Vercel 项目设置 → Deployments → 重新部署时，取消勾选 "Use existing Build Cache"，强制清缓存重新构建。

问题二：新文章不出现在首页

排查过程

查看 Vercel 运行日志，确认 ISR 正常工作（vercelCache: "STALE"），每次请求都有调用 Notion API，获取到 43 条数据，无报错

在网站搜索，确认新文章能被搜到（说明文章数据存在）

查看 SiteDataApi.js 第 372–375 行过滤逻辑

根本原因：新版本新增了 slug 必填过滤

新版本在 allPages 过滤时加了 post?.slug && 判断，没有填写 slug 的文章会被完全过滤掉，不会出现在任何位置（包括首页、搜索之外的列表）。旧版本没有这个限制。

修复方法：在 Notion 数据库中为每篇 Post 类型的文章填写 slug 字段。

问题三：有 slug 的文章仍不在首页前列

根本原因：排序方式为 `notion`，且只显示前 12 篇

conf/post.config.js 默认配置：

Notion 视图里旧文章排在前面，新文章被截断在第 12 位之后。

修复方法：在 Vercel 添加环境变量：

文章按发布日期倒序排列，最新文章始终出现在首页。

三、Notion 数据库字段设计指南

字段一览

字段	Notion 列类型	是否必填	说明
title	标题（Title）	✅ 必填	页面标题，Notion 默认列
type	单选（Select）	✅ 必填	决定记录角色，见下方说明
status	单选（Select）	✅ 必填	控制是否在网站上显示
slug	文本（Text）	Post 必填	URL 路径标识
summary	文本（Text）	建议填	文章摘要，显示在列表卡片
icon	文本（Text）	可选	菜单图标，填 Font Awesome 类名
date	日期（Date）	建议填	发布日期；不填则用创建时间代替
tags	多选（Multi-select）	可选	文章标签
category	单选（Select）	可选	文章分类
password	文本（Text）	可选	加密文章的明文密码

type 字段：五种类型的区别

`Post` — 博客文章

显示在首页文章列表

必须填写 slug，最终 URL = /article/<slug>（由 POST_URL_PREFIX 配置决定前缀）

参与标签、分类统计

支持按日期排序和定时发布

`Page` — 独立内容页

不出现在文章列表

URL = /<slug>，例如 /about

在 CUSTOM_MENU = true（新版默认）时不会自动出现在导航栏，需要配合 Menu 条目使用

正文内容完整渲染，适合「关于我」「友链」等独立页面

`Menu` — 顶部导航菜单项

出现在导航栏

slug 填写跳转 URL：内链如 /about，外链如 https://...

slug 留空或填 # → 变为可展开父菜单（不跳转）

icon 字段填 Font Awesome 类名，例如 fas fa-user

`SubMenu` — 子菜单项

必须在 Notion 视图中紧跟某个 Menu 行下方（系统按顺序归属，不是 Notion 父子层级）

只支持两级菜单，不可再嵌套

同样支持 icon

`Notice` — 全站公告

显示在页面顶部公告横幅

只取第一条 Published 状态的 Notice

slug 可填写「查看详情」的跳转链接

status 字段说明

值	效果
Published	正常显示
Invisible	隐藏（不出现在列表），但 URL 直接访问仍可打开
其他 / 空	完全不加载，相当于草稿

slug 字段的规则

Post 类型：

用户在 Notion 填写的 slug（如 my-post）会被代码自动加上前缀，变成 article/my-post

前缀由环境变量 NEXT_PUBLIC_POST_URL_PREFIX 控制，默认为 article

支持动态前缀：article/%year%/%month%/%day% 可生成带日期的 URL

Page 类型：

slug 不加前缀，直接用作路径，如 slug=about → 访问 /about

Menu / SubMenu 类型：

slug 就是跳转目标 URL，外链需带 https://

外链自动在新标签页打开

icon 字段的正确用法

仅对 Menu / SubMenu 类型有效，渲染为：

只支持 Font Awesome 类名，不支持 emoji。例如：

fas fa-home → 房子图标

fas fa-user → 人物图标

fas fa-archive → 归档图标

fas fa-tag → 标签图标

去 fontawesome.com/icons 搜索 Free 图标，复制类名即可。

内置路由（slug 可直接指向）

URL	功能
`/`	首页
`/archive`	文章归档（时间轴）
`/search`	搜索
`/category`	分类列表
`/category/[名称]`	某分类的文章
`/tag`	标签列表
`/tag/[名称]`	某标签的文章
`/rss/feed.xml`	RSS 订阅

没有内置周刊页面。推荐做法：给周刊文章统一打 weekly 标签，菜单 slug 填 /tag/weekly。

菜单配置实战示例

在 Notion 数据库中按顺序排列（行的顺序即菜单顺序）：

title	type	status	slug	icon
首页	Menu	Published	`/`	`fas fa-home`
周刊	Menu	Published	`/tag/weekly`	`fas fa-link`
文章	Menu	Published	`#`	`fas fa-archive`
┣ 历史归档	SubMenu	Published	`/archive`	`fas fa-clock`
┗ 文章分类	SubMenu	Published	`/category`	`fas fa-th`
关于我	Menu	Published	`/about`	`fas fa-info`
搜索	Menu	Published	`/search`	`fas fa-search`

关于我页面的完整搭建方式

需要两条记录配合：

内容页（type = Page）：写正文内容，slug = about，URL 为 /about

菜单入口（type = Menu）：slug = /about，让导航栏出现入口

四、右侧栏组件与顺序调整

hexo 主题右侧栏（themes/hexo/components/SideRight.js）的组件顺序硬编码在代码里，Notion 配置无法改变：

想调整顺序：直接编辑 SideRight.js，移动 JSX 组件位置即可，提交后 Vercel 自动重新部署。

各组件内容来源：

InfoCard：blog.config.js 里的 AUTHOR、BIO、头像

LatestPostsGroup：自动取最新 6 篇 Post 文章

Announcement：Notion 数据库第一条 type=Notice 且 status=Published 的记录

五、SEO 评估

Lighthouse 评分（2026-05-07）

维度	桌面	移动
SEO	100	100
Accessibility	96	96
Best Practices	77	77

SEO 技术层（全部通过）

<title> 标签 ✅

<meta description> ✅

链接文字具备描述性 ✅

链接可被爬虫抓取 ✅

robots.txt 有效 ✅

图片有 alt 属性 ✅

hreflang 多语言标签 ✅

未被 noindex 屏蔽 ✅

待改进项

第三方 Cookie（Best Practices 扣分主因）

不蒜子访问统计（busuanzi.ibruce.info）会设置第三方 cookie，Chrome 已逐步限制。建议替换为 Umami 或 Vercel Analytics，无 cookie、隐私友好。

缺少结构化数据（JSON-LD）

目前没有 BlogPosting 类型的 JSON-LD 标记，Google 无法展示富摘要（Rich Snippet）。在文章页模板中添加：

Google Search Console 提交 Sitemap

/sitemap.xml 已存在，但需要主动到 Google Search Console 提交，才能加速新文章收录。

SEO 深层建议

维度	现状	建议
外链/反链	几乎没有	在其他平台发布并注明原文链接
内容更新频率	不稳定	保持每周 1-2 篇，Google 会提高抓取频率
关键词布局	未专门优化	文章标题和摘要中自然包含目标关键词
Core Web Vitals	未检测	性能分数直接影响排名，建议单独用 PageSpeed Insights 检测

六、总结

问题	原因	修复方案
主题未切换	webpack alias 构建时写死，缓存未失效	Vercel 重新部署时清除构建缓存
新文章不显示	新版本 allPages 过滤要求 slug 非空	为每篇 Post 文章填写 slug
新文章排在后面	排序方式为 notion 视图顺序	添加环境变量 `NEXT_PUBLIC_POST_SORT_BY=date`
主题切回 hexo	需要清缓存重建	同主题问题，清缓存后生效

配置变更汇总（Vercel 环境变量）：

作者：可夫小子 | 网站：koffuxu.com | 更新时间：2026-05-07