基于Next.js与Notion API构建高性能静态博客全攻略

1. 项目概述：用Notion驱动你的个人网站

如果你和我一样，既想拥有一个完全自定义、性能出色的个人博客或作品集网站，又不想被繁琐的后台内容管理和数据库设计所束缚，那么这个项目可能就是你的“梦中情栈”。Next.js Notion Starter Kit 的核心思路非常巧妙：它把 Notion 这个我们日常用来记笔记、做规划的“瑞士军刀”，变成了一个功能齐全的CMS（内容管理系统）。你只需要在 Notion 里像平时一样写文章、整理项目，这个工具就能自动将它们变成一个高速、美观的静态网站。

我最初接触这个方案是因为受够了传统博客平台（如 WordPress）的臃肿和主题开发的复杂性，也尝试过一些“无头CMS”，但总觉得为了管理几篇文章而维护一个独立的后台有些杀鸡用牛刀。Notion 的块编辑器体验极佳，支持富文本、嵌入、数据库，而且跨平台同步无缝。这个 Starter Kit 的出现，完美地将 Notion 的内容创作体验与 Next.js 的现代前端开发能力结合了起来。它不仅仅是一个“玩具”，像原作者 Travis Fischer 的个人网站 transitivebullsh.it 这样成熟的站点也完全基于此构建，这证明了其生产可用性。

简单来说，这个工具适合以下几类人：前端开发者，希望快速搭建一个技术博客来展示作品和分享知识；创作者或写作者，希望拥有一个完全属于自己的、设计精美的发布平台，而无需学习复杂的建站工具；团队或个人，需要一个小型的产品展示页或文档站，并希望内容更新能像编辑文档一样简单。它的优势在于“内容归你，呈现归我”——你享有 Notion 提供的极致自由的内容组织能力，同时又能获得一个由 Next.js 加持的、在速度和SEO方面表现优异的现代化网站。

2. 核心架构与设计思路拆解

2.1 为什么是 Next.js + Notion 这个组合？

这个组合的成功并非偶然，它精准地击中了个人建站者的几个核心痛点。首先，Next.js作为 React 的元框架，提供了开箱即用的服务端渲染（SSR）、静态站点生成（SSG）、图像优化、API路由等能力。这意味着你的网站天生就具备优秀的首屏加载速度和搜索引擎友好性。对于个人站点来说，SSG模式尤其合适：在构建时一次性从 Notion 拉取所有数据并生成静态HTML文件，部署后访问速度极快，且几乎零服务器成本。

其次，Notion作为一个“全能型”工具，其 API 暴露了页面和数据库的所有结构化数据。react-notion-x这个库扮演了关键角色，它负责将 Notion API 返回的复杂块数据（blocks）渲染成高质量的 React 组件。这样一来，Notion 中丰富的块类型——标题、列表、代码块、引用、表格、甚至内嵌的数据库视图——都能在网页上得到近乎原生的渲染。

这个 Starter Kit 的设计哲学是“约定优于配置”。它没有试图创建一个复杂的后台或定义一套全新的内容模型，而是完全拥抱 Notion 已有的数据结构。你的网站结构就是你 Notion 工作区的页面层级关系；你的文章样式就是你在 Notion 里设置的样式。这种极低的迁移和学习成本，是它最大的吸引力之一。

2.2 数据流与渲染流程解析

理解数据如何从 Notion 流动到用户浏览器，对于后续的定制和问题排查至关重要。整个流程可以概括为以下几个步骤：

1. 构建时数据获取：在运行npm run build时，Next.js 会执行getStaticProps和getStaticPaths函数。这些函数会调用 Starter Kit 封装的逻辑，通过 Notion 官方 API（需要集成）或更常见的第三方 Notion API 客户端（如notion-client），根据你在site.config.ts中配置的rootNotionPageId，递归地获取该页面及其所有子页面的数据。
2. 数据转换与缓存：获取到的原始 Notion 数据会被处理并缓存。这里涉及到一个关键点：Notion 的页面ID（Page ID）到友好URL（Slug）的映射。系统会自动根据页面标题生成一个 slug（例如，“My Awesome Post” -> “my-awesome-post”），并在生产环境中去掉冗长的页面ID，使URL更简洁。
3. 静态页面生成：Next.js 利用处理好的数据，为每个页面生成对应的静态 HTML 文件。react-notion-x的组件负责将 Notion 块数据渲染成实际的 DOM 结构。同时，一些增强功能如预览图片生成、社交元标签（Open Graph）创建也会在这个阶段完成。
4. 客户端水合：生成的静态页面被发送到浏览器后，React 会进行“水合”，使页面变得可交互。搜索功能（CMD+K）、深色模式切换、目录滚动监听等动态特性都在客户端激活。
5. 实时性考虑：对于需要最新数据的场景（比如评论功能），可以通过 Next.js 的 API Routes 创建后端接口，或者使用getServerSideProps进行服务端渲染。但就纯内容展示而言，SSG 模式配合定期的重新部署（例如通过 GitHub Actions 或 Vercel 的定时部署）已经足够。

这种架构带来的好处是显而易见的：性能极致（静态文件 + CDN）、安全性高（无动态数据库）、成本低廉（托管在 Vercel 等平台有免费额度）。唯一的“动态”部分——从 Notion 读取数据——也发生在构建阶段，不会影响最终用户的访问速度。

3. 从零开始的详细配置与部署指南

3.1 环境准备与项目初始化

首先，你需要一个 Node.js 环境，版本建议在 16 或以上。我推荐使用nvm来管理 Node 版本，这样可以避免全局依赖冲突。

# 使用 nvm 安装并切换 Node.js 版本 nvm install 18 nvm use 18

接下来，获取项目代码。最直接的方式是 Fork 原仓库到你的 GitHub 账户下，这样你既能获得一个独立的起点，也方便后续同步上游更新。

# 克隆你 Fork 后的仓库 git clone https://github.com/你的用户名/nextjs-notion-starter-kit.git cd nextjs-notion-starter-kit

安装项目依赖，这里使用npm或yarn均可。

npm install # 或 yarn install

完成安装后，不要急着运行。整个项目的配置核心只有一个文件：site.config.ts。在动手修改它之前，我们需要先搞定 Notion 端的设置。

3.2 Notion 工作区与页面配置

这是最关键的一步，决定了你的网站能展示什么内容。

1. 创建一个公开页面：在你的 Notion 工作区中，创建一个新页面作为你网站的“根目录”。你可以直接复制原作者提供的 模板页面 ，也可以从头创建。这个页面将作为你网站的首页。
2. 获取页面ID：进入你刚创建的页面，在浏览器地址栏中，你可以看到类似https://www.notion.so/你的工作区/7875426197cf461698809def95960ebf的链接。末尾的那一串字符7875426197cf461698809def95960ebf就是该页面的Page ID。复制它。
3. 设置页面为公开：点击页面右上角的“分享”按钮，然后打开“公开访问”开关。这样，Starter Kit 才能通过 Notion API 读取到页面内容。
4. （可选）获取工作区ID：工作区ID（Space ID）在某些高级配置中可能会用到。获取它的一个简单方法是：在浏览器中打开你的公开 Notion 页面，按 F12 打开开发者工具，在 Console 标签页中输入window.block.space_id并回车，控制台就会打印出你的 Space ID。

实操心得：我建议专门为这个网站创建一个新的 Notion 工作区，或者至少使用一个独立的页面分支。避免将个人私密笔记与公开网站内容混在一起，便于管理。另外，Notion 页面的图标和封面图会被自动用作网站的 Favicon 和 Open Graph 图片，所以精心挑选一下会让你的站点看起来更专业。

3.3 核心配置文件site.config.ts详解

现在，打开项目根目录下的site.config.ts文件。这个文件定义了网站的几乎所有元信息。我们逐项进行配置：

// site.config.ts import { SiteConfig } from './src/types' export const siteConfig: SiteConfig = { // 1. 基础信息 name: '我的技术博客', // 网站名称，会显示在标题和页脚 domain: 'www.myblog.com', // 你的域名，用于生成绝对URL author: '你的名字', // 作者名 // 2. Notion 核心配置 rootNotionPageId: '7875426197cf461698809def95960ebf', // 替换为你复制的根页面ID rootNotionSpaceId: null, // 可选，如果你知道你的 Space ID 可以填在这里 // 3. 基础功能开关 isPreviewImageSupportEnabled: true, // 是否启用预览图生成（建议开启，但首次构建慢） isRedisEnabled: false, // 是否使用 Redis 缓存预览图（初期可关闭） // 4. SEO 与社交 description: '这是我的个人博客，分享技术思考和项目经验。', // 网站描述 socialImageTitle: '我的技术博客', // 社交图片上显示的标题 socialImageSubtitle: '探索代码与创意', // 社交图片上显示的子标题 // 5. 页面相关 pageUrlOverrides: null, // 自定义页面URL映射，高级功能 navigationStyle: 'default', // 导航样式 navigationLinks: [ // 自定义导航链接 { title: '关于', pageId: '关于页面的ID' }, { title: '项目', pageId: '项目数据库页面的ID' } ] }

重点参数解析：

• rootNotionPageId：必须正确填写，否则网站无法获取内容。
• isPreviewImageSupportEnabled：强烈建议开启。它会为文章中的图片生成低质量占位符（LQIP），实现图片加载时的模糊到清晰效果，极大提升体验。但注意，首次构建时需要为每张图片生成这个占位符，如果文章图片很多，构建时间会很长。
• isRedisEnabled：如果你开启了预览图支持，并且网站内容较多，构建时间让你难以忍受，那么可以启用 Redis。它会缓存生成的预览图，后续构建时直接读取缓存，速度飞快。对于个人博客，如果更新不频繁，可以暂时关闭。

3.4 本地运行与调试

配置完成后，就可以在本地启动开发服务器了。

npm run dev

访问http://localhost:3000，你应该能看到你的 Notion 根页面内容被渲染成了网站。开发环境下的URL会包含 Notion 页面ID，例如/my-home-page-d1b5dcf8b9ff425b8aef5ce6f0730202，这是为了方便调试。

在本地开发时，你可以：

• 实时热重载：修改site.config.ts或 React 组件，页面会即时更新。
• 查看Notion数据：在页面上右键“检查”，在开发者工具的“网络”选项卡中，可以找到对/_notion/的请求，查看从 Notion 获取的原始数据，对于调试数据问题很有帮助。
• 测试功能：尝试搜索（CMD+K）、切换深色模式、查看自动生成的目录是否正常工作。

3.5 部署到 Vercel

Vercel 是这个项目推荐的部署平台，因为它与 Next.js 同出一源，集成度最高，并且提供了非常慷慨的免费套餐。

1. 推送代码：将你修改后的代码提交并推送到你的 GitHub 仓库。

   git add . git commit -m "初始配置" git push origin main

2. 导入到 Vercel：登录 Vercel ，点击“New Project”，从 GitHub 导入你刚才推送的仓库。
3. 配置项目：Vercel 会自动检测到这是一个 Next.js 项目。在配置页面，你通常不需要修改任何构建设置。直接点击“Deploy”。
4. 关键设置：关闭部署保护：部署完成后，有一个至关重要的步骤。进入 Vercel 项目的 “Settings” -> “Deployment Protection”。确保 “Vercel Authentication” 是关闭状态。如果这个选项是开启的，那么社交媒体爬虫（如 Twitter、Facebook 的机器人）在尝试抓取你网站为分享文章生成的预览图时，会遇到 401 未授权错误，导致分享链接没有图片。这是新手最容易踩的坑。
5. 配置自定义域名（可选）：在 “Settings” -> “Domains” 中，添加你购买的域名，并按照指引配置 DNS 解析记录。

部署成功后，你的网站就上线了！Vercel 会自动为每次向main分支的推送触发新的部署，实现持续集成。

4. 高级功能定制与优化实践

4.1 自定义样式与主题

虽然 Starter Kit 提供了不错的默认样式，但要让网站真正具有个人特色，样式定制是必须的。所有的核心样式都集中在styles/notion.css这个文件中。

react-notion-x为每个 Notion 块都生成了一个唯一的 CSS 类名，格式为.notion-block-{pageId}。这给了我们极其精细的控制能力。例如，你想隐藏某个特定的块：

/* 在 styles/notion.css 末尾添加 */ .notion-block-260baa77f1e1428b97fb14ac99c7c385 { display: none; }

更常见的需求是修改全局样式，比如字体、颜色、间距。你可以通过覆盖react-notion-x提供的 CSS 变量来实现。在styles/globals.css或styles/notion.css的开头添加：

:root { /* 修改默认字体 */ --notion-font: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, sans-serif; /* 修改浅色主题背景色 */ --bg-color: #fafafa; /* 修改深色主题背景色 */ --bg-color-dark: #1a1a1a; /* 修改代码块主题 */ --notion-code-background: #f6f8fa; }

注意事项：修改样式时，建议使用浏览器的开发者工具，先定位到目标元素的类名，再进行覆盖。由于 CSS 优先级的问题，有时可能需要使用!important来强制生效，但应尽量避免，优先通过提高选择器特异性来解决。

4.2 优化图片加载：预览图与 Redis 缓存

图片是影响网站性能的最大因素之一。这个项目通过next/image组件和lqip-modern库实现了现代化图片优化。

• next/image：自动提供图片的懒加载、按视口尺寸裁剪、WebP格式转换（如果浏览器支持）等功能。
• lqip-modern：在构建时，为每张图片生成一个极小的、模糊的 Base64 编码预览图。图片加载时，先显示这个模糊预览图，待原图加载完成后再平滑过渡，这就是所谓的“模糊到清晰”效果。

启用 Redis 缓存： 如果你的网站有大量图片，每次构建都重新生成预览图会非常耗时。启用 Redis 可以缓存这些生成的预览图。

1. 获取 Redis 服务：你可以使用 Upstash 或 Redis Labs 等云服务商，它们都提供免费的 Redis 实例。
2. 配置环境变量：在 Vercel 项目的 “Settings” -> “Environment Variables” 中，添加REDIS_HOST和REDIS_PASSWORD（或REDIS_URL，具体取决于你的 Redis 提供商给你的连接字符串格式）。
3. 修改配置：将site.config.ts中的isRedisEnabled设为true。
4. 本地开发：在项目根目录创建.env.local文件，填入相同的REDIS_HOST和REDIS_PASSWORD，以便本地构建也能使用缓存。

# .env.local REDIS_HOST='your-redis-host.upstash.io' REDIS_PASSWORD='your-redis-password'

完成以上步骤后，首次构建仍然会慢，因为需要生成并填充缓存。但从第二次构建开始，速度就会有质的飞跃。

4.3 实现自定义页面路由与导航

默认情况下，页面的URL由 Notion 页面标题自动生成。但有时我们想要更简洁或特定的URL。

方法一：使用Slug属性（推荐）在你的 Notion 数据库（或作为数据库的页面）中，为每篇文章添加一个属性，属性类型为“Text”，名称就叫做Slug。在这个属性里填写你想要的URL路径，例如my-first-post。系统会优先使用这个Slug值，而不是页面标题来生成URL。

方法二：使用pageUrlOverrides配置在site.config.ts中，你可以直接映射特定的 Notion 页面ID到自定义路径。

export const siteConfig: SiteConfig = { // ... 其他配置 pageUrlOverrides: { // 'Notion页面ID': '自定义路径' 'dfc7f709-ae3e-42c6-9292-f6543d5586f0': '/about-me', 'a1b2c3d4e5f6': '/projects/2024-ai-tool' } }

自定义导航栏：navigationLinks配置项允许你在网站头部添加自定义链接。这些链接可以指向你 Notion 工作区内的其他页面。

navigationLinks: [ { title: '首页', pageId: '你的根页面ID' }, { title: '所有文章', pageId: '你的文章数据库页面ID' }, { title: '关于', pageId: '关于页面ID' }, { title: 'GitHub', url: 'https://github.com/你的用户名' } // 也支持外部链接 ]

4.4 集成数据分析与评论系统

一个完整的博客需要了解访问情况和与读者互动。

数据分析： 项目内置支持 Fathom 和 PostHog 两种轻量级分析工具。以 Fathom 为例：

1. 注册 Fathom 并创建一个新站点，获取站点ID。
2. 在 Vercel 环境变量中添加NEXT_PUBLIC_FATHOM_ID，值为你的站点ID。
3. 重新部署项目。Fathom 的统计脚本将自动注入到你的网站中。

评论系统： Starter Kit 本身不包含评论功能，但我们可以轻松集成第三方服务，如 Giscus（基于 GitHub Discussions）或 Utterances（基于 GitHub Issues）。以 Giscus 为例：

1. 按照 Giscus 官网指引进行配置，获取一段脚本代码。
2. 在项目中创建一个客户端组件，例如app/components/Giscus.tsx，使用useEffect在组件挂载后动态加载 Giscus 脚本。
3. 在你的文章页面模板（例如app/[pageId]/page.tsx）中引入这个Giscus组件。你可以通过判断页面的properties中是否有“允许评论”的复选框属性，来决定是否在特定文章下显示评论框。

5. 常见问题排查与性能优化实录

在实际使用中，你肯定会遇到一些问题。下面是我在搭建和维护过程中遇到的一些典型情况及其解决方案。

5.1 构建失败与数据获取错误

问题：构建时卡住或报错，提示 Notion API 相关错误。

• 可能原因1：页面未公开。这是最常见的原因。请务必回到 Notion，确认你设置的rootNotionPageId对应的页面，以及它所有子页面的分享权限都是“公开”。
• 可能原因2：网络问题。Notion API 在国内访问可能不稳定。尝试在site.config.ts中配置一个代理，或者使用云构建环境（如 Vercel 本身）。
• 可能原因3：API 速率限制。如果你一次性获取的页面非常多，可能会触发 Notion API 的速率限制。可以考虑分批次构建，或者为notion-client增加重试逻辑。

问题：本地运行正常，部署到 Vercel 后页面空白或样式错乱。

• 排查步骤：
  1. 检查 Vercel 的部署日志。在 Vercel 项目控制台的 “Deployments” 标签页，点击最新的部署，查看构建日志。错误信息通常会在这里显示。
  2. 检查环境变量。确认在 Vercel 中设置的环境变量（如REDIS_HOST）名称和值是否正确。
  3. 检查site.config.ts。确保其中没有引用本地路径或仅在本地存在的资源。

5.2 样式与布局问题

问题：Notion 中的某些内容（如特定类型的数据库视图、复杂布局）渲染不正常或丢失。

• 原因与解决：react-notion-x虽然强大，但并未 100% 支持所有 Notion 块类型。一些非常新的或复杂的块（如 Synced Block、某些高级数据库视图）可能渲染不佳。解决方案通常是：在 Notion 中简化该部分内容的格式，或者通过自定义 React 组件来覆盖特定块类型的渲染逻辑。你可以查阅react-notion-x的文档，了解如何注册自定义渲染器。

问题：移动端布局异常。

• 解决：项目默认是响应式的，但如果你添加了自定义样式，可能会破坏响应式布局。使用 Chrome 开发者工具的“设备工具栏”进行移动端调试，确保你的自定义 CSS 使用了相对单位（如rem,%,vw）而非绝对单位（如px），并合理运用媒体查询（@media）。

5.3 性能优化 checklist

当你的网站文章越来越多时，以下优化可以保持其速度：

1. 启用 Redis 缓存：如前所述，这对缩短构建时间至关重要。
2. 优化图片源：Notion 托管的图片有时加载较慢。可以考虑使用 Next.js 的next/image配置一个自定义的图片加载器，或者将图片迁移到更快的 CDN（如 Cloudinary、Imgix），但这需要修改react-notion-x的图片渲染逻辑，属于高级定制。
3. 增量静态再生：对于更新不频繁的页面（如关于页），可以在getStaticProps中设置一个较长的revalidate时间（例如一天），减少不必要的重复构建。
4. 代码分割：确保你引入的第三方库（如图表库、特定组件库）都被正确地进行代码分割，不要全部打包到主 bundle 中。
5. 分析 Bundle 大小：使用@next/bundle-analyzer分析生产环境的打包文件，找出体积过大的模块并优化。

5.4 内容管理与 SEO 最佳实践

• 利用 Notion 数据库进行内容管理：不要只用简单的页面列表。创建一个“文章”数据库，为每篇文章添加“发布日期”、“标签”、“摘要”、“状态”（草稿/已发布）等属性。这样，你可以在网站上轻松实现按标签筛选、按日期归档等功能。Starter Kit 可以很好地渲染数据库的“列表视图”或“画廊视图”作为文章索引页。
• 优化 SEO：项目已自动生成基础的 Open Graph 和 Twitter Card 标签。你还可以：
  • 在site.config.ts中完善description。
  • 为重要的页面在 Notion 页面属性中添加“Description”字段，并在代码中读取该字段作为页面的专属meta description。
  • 确保网站的sitemap.xml和robots.txt正确生成（可能需要额外配置 Next.js 的rewrites或自定义 API 路由）。
• 处理重复标题：如果 Notion 中有两个页面标题相同，它们生成的 slug 也会相同，导致构建错误。系统会报错提示你。解决方法就是修改其中一个页面的标题，或者使用前面提到的Slug属性或pageUrlOverrides来手动指定不同的路径。

我个人在深度使用这个 Starter Kit 近一年后，最大的体会是它完美平衡了“自由度”和“便利性”。你无需关心服务器、数据库运维，又能获得一个性能顶尖、设计可控的网站。它尤其适合那些内容驱动、更新频率适中、且开发者希望专注于内容创作而非工具维护的场景。当然，它也不是万能的，对于需要高度复杂交互或实时数据的应用，还是需要更传统的全栈方案。但对于一个个人博客、作品集或知识库来说，它提供的方案已经足够优雅和强大。