NotionNext：基于Notion API与Next.js的静态博客搭建指南

1. 项目概述与核心价值

如果你和我一样，既想拥有一个完全自主、设计精美的个人博客，又不想在服务器运维、数据库管理和复杂的后台开发上耗费大量精力，那么 NotionNext 这个项目可能就是为你量身定做的。它本质上是一个“桥梁”，将 Notion 这个强大的笔记与知识管理工具，变成了一个功能齐全的静态博客生成器。你只需要在 Notion 里像平时记笔记一样写文章，NotionNext 就能自动抓取这些内容，并生成一个部署在 Vercel 上的高速、现代化的网站。

我第一次接触这个方案时，最打动我的就是它的“无感写作”体验。我不再需要为了发一篇博客，去登录某个平台的后台，在简陋的编辑器里折腾格式。我的所有草稿、灵感、成文都自然地沉淀在 Notion 这个我每天都在用的工具里。当我想发布时，只需要在 Notion 中把一个页面的状态从“草稿”改为“已发布”，或者简单地点击一下 Vercel 的“重新部署”按钮，我的博客就自动更新了。这种将内容管理（Notion）与前端呈现（Next.js）分离的架构，不仅解放了创作者，也让博客的访问速度极快，因为生成的是静态页面。

这个项目适合所有希望低成本、高效率建立个人品牌的内容创作者、开发者、学生或任何有分享欲的人。你不需要是 React 或 Next.js 专家，甚至不需要懂命令行，按照教程一步步操作也能成功。当然，如果你有一定的前端开发基础，那么 NotionNext 提供的丰富主题和高度可定制性，将给你带来更大的发挥空间。

2. 核心架构与方案选型解析

NotionNext 的成功，关键在于它巧妙地组合了几项当下非常流行且成熟的技术，形成了一个稳定、高效且开发者友好的技术栈。理解这个架构，能帮助你在后续的定制和问题排查中游刃有余。

2.1 为什么是 Next.js + Notion API？

Next.js是这个项目的基石。它是一个基于 React 的框架，但提供了两大杀手锏功能，完美契合博客需求：

1. 服务端渲染（SSR）与静态站点生成（SSG）：Next.js 可以在构建时（next build）就提前获取 Notion 的数据，并生成纯静态的 HTML 文件。这意味着用户访问你的博客时，加载速度如同访问一个纯 HTML 页面，对 SEO 极其友好。同时，它也支持服务端渲染，适合需要实时数据的场景，但博客这种内容相对固定的场景，SSG 是首选。
2. 基于文件系统的路由：在pages目录下创建一个about.js文件，就会自动生成/about路由。这种约定大于配置的方式，让博客的页面管理变得非常直观，添加一个新页面（如作品集、友链）只需新建一个文件。

Notion API是内容的源头。Notion 官方提供的 API 允许我们以编程方式读取数据库（Database）和页面（Page）的内容。NotionNext 的核心工作就是：调用这个 API，获取你指定的 Notion 数据库里的所有文章（每条数据库记录对应一篇博客），然后将 Notion 特有的区块（Block）数据，转换成 React 组件可以渲染的格式。

这个组合的优势在于，它将内容管理和网站渲染彻底解耦。Notion 作为无头 CMS（Headless CMS），你享受到了它优秀的编辑体验、版本历史和协作功能；而 Next.js 作为前端，负责提供极致的访问性能和灵活的前端表现。任何一方的升级或变更，对另一方的影响都降到最低。

2.2 样式方案：Tailwind CSS 的实用性

项目选择了Tailwind CSS作为样式方案。这是一个实用优先（Utility-First）的 CSS 框架。你可能习惯了写.button { padding: 8px 16px; }，而在 Tailwind 里，你直接在 HTML/JSX 元素上写className=“px-4 py-2”。

对于博客项目来说，这带来了两个巨大好处：

1. 极高的定制自由度：主题开发者可以快速构建出独特的设计，而无需担心全局 CSS 的类名冲突。每个样式都是局部的。
2. 构建产物极小：Tailwind 会通过扫描你的源代码，只打包你实际使用到的 CSS 类，最终生成的 CSS 文件通常只有几十 KB，这对博客的加载速度是质的提升。

当然，初学者可能需要记忆一些类名，但一旦熟悉，开发效率会非常高。项目提供的多个主题，本质上就是一套预设好的 Tailwind 类名集合。

2.3 部署平台：Vercel 与 Zeabur 的抉择

官方主推Vercel，这是有充分理由的。Vercel 是 Next.js 框架的创建者提供的部署平台，两者结合堪称“天作之合”。

• 无缝集成：关联 GitHub 仓库后，每次git push都会自动触发部署。Vercel 能自动识别 Next.js 项目并进行最优化的构建和部署。
• 全球 CDN：生成的静态文件会自动分发到全球的边缘网络，确保任何地方的访问者都能快速打开你的博客。
• 完全免费：对于个人博客级别的流量和构建次数，Vercel 的免费套餐（Hobby Plan）完全够用，并且提供了自定义域名、SSL 证书等必备功能。

项目也提到了Zeabur，这是一个新兴的、对中文开发者更友好的云平台。它的优势在于：

• 国内访问优化：服务节点在亚洲，国内访问速度可能更有保障。
• 一体化服务：除了部署，还提供了数据库、存储等更多后端服务，适合未来想为博客增加动态功能的用户。
• 同样友好的免费额度。

对于绝大多数用户，我建议首选 Vercel，因为其与 Next.js 的集成体验是最好的，文档和社区资源也最丰富。如果你在部署过程中遇到网络问题，或者希望探索更多集成服务，Zeabur 是一个优秀的备选方案。

注意：无论选择哪个平台，请务必理解它们都是“Serverless”或“平台即服务”（PaaS）。你不需要管理服务器，只需要关心你的代码和配置。这极大地降低了运维门槛。

3. 从零开始的完整部署实操指南

理论说再多，不如动手做一遍。下面我将以最常用的 Vercel 部署路径为例，带你一步步搭建起自己的 NotionNext 博客。请严格按照步骤操作，我会在关键点附上我踩过的坑和经验。

3.1 前期准备：三样必备品

在开始之前，你需要准备好以下三样东西，缺一不可：

1. 一个 Notion 账户：如果你还没有，去 notion.so 免费注册一个。
2. 一个 GitHub 账户：用于托管你的博客代码。
3. 一个 Vercel 账户：可以直接用 GitHub 账户授权登录，非常方便。

3.2 第一步：复制模板仓库并初始化

这是最关键的一步，目的是在你自己的 GitHub 下创建一个 NotionNext 项目的副本。

1. 访问官方仓库： https://github.com/tangly1024/NotionNext
2. 点击绿色的“Use this template”按钮，然后选择“Create a new repository”。

   重要提示：不要直接Fork！使用“Use this template”功能会创建一个属于你的、独立的全新仓库，与上游仓库脱钩，方便你后续自由定制，而不会在合并更新时产生冲突。

3. 为你的新仓库起个名字，比如my-blog，选择公开（Public），然后点击创建。
4. 创建成功后，将这个新仓库克隆到你的本地电脑（如果你打算做代码定制），或者直接进入下一步。对于大多数只想快速建站用户，可以跳过本地克隆，完全在云端操作。

3.3 第二步：在 Notion 中创建数据库并获取密钥

你的博客文章都将存储在一个 Notion 数据库里。我们需要创建这个数据库，并让 NotionNext 有权限读取它。

1. 创建数据库：

   • 在你的 Notion 工作区新建一个页面。
   • 输入/唤出命令菜单，选择 “Table - Inline” 或 “Table - Full page”。一个空表格（数据库）就创建好了。
   • 我们需要为博客文章定义一些属性（Properties）。请至少确保有以下列（列名严格对应，类型按建议设置）：
     • Title(默认存在，类型为Title): 文章标题。
     • slug(类型为Text): 文章的唯一网址标识符，如my-first-post。此项必须创建，且名称必须为小写slug。
     • type(类型为Select): 页面类型。创建两个选项：Post(用于博客文章) 和Page(用于关于、归档等独立页面)。默认值设为Post。
     • status(类型为Select): 文章状态。创建两个选项：Published(已发布) 和Invisible(隐藏)。NotionNext 默认只会抓取status为Published的文章。
     • summary(类型为Text): 文章摘要，可选。
     • date(类型为Date): 发布日期。
     • tags(类型为Multi-select): 文章标签。
   • 你可以根据喜好添加更多列，如category（分类）、cover（封面图链接）等。一个标准的数据库视图如下所示：

     Title	slug	type	status	date	tags
     我的第一篇文章	my-first-post	Post	Published	2023-10-27	教程,Notion
     关于我	about	Page	Published	-	-

2. 获取数据库ID：

   • 在 Notion 中打开你刚创建的数据库。
   • 浏览器地址栏的 URL 类似于：https://www.notion.so/yourworkspace/a0a1b2c3d4e5f67890123456789abcdef?v=...
   • a0a1b2c3d4e5f67890123456789abcdef这一长串字符就是你的数据库 ID。把它复制下来。

3. 创建集成（Integration）并获取密钥：

   • 访问 https://www.notion.so/my-integrations 。
   • 点击 “+ New integration”。
   • 为你的集成起个名字，例如 “My Blog”。
   • 关联的工作空间选择你创建数据库的那个。
   • 点击 “Submit” 创建。创建成功后，你会来到集成详情页。
   • 在这个页面，找到并复制“Internal Integration Token”这一长串以secret_开头的字符串。这就是你的NOTION_TOKEN，请像保管密码一样保管它，切勿泄露或提交到公开仓库。
   • 最后一步，将你的集成分享（Share）给刚刚创建的数据库。回到你的数据库页面，点击右上角的 “···” -> “Add connections”，然后在列表中找到你刚创建的 “My Blog” 集成，点击添加。这样，这个集成就有权限读取这个数据库了。

3.4 第三步：在 Vercel 上部署并配置环境变量

现在，我们让 Vercel 去构建和部署你的博客。

1. 登录 Vercel：用 GitHub 账号登录 vercel.com 。
2. 导入项目：点击 “Add New…” -> “Project”，你会看到 GitHub 中你刚创建的my-blog仓库，点击 “Import”。
3. 配置项目：
   • Framework Preset: Vercel 会自动检测为 Next.js，保持默认即可。
   • Root Directory: 保持默认（./）。
   • Build and Output Settings: 保持默认。
4. 配置环境变量（最关键的一步）：
   • 在环境变量配置区域，点击添加。
   • 你需要添加以下两个变量：
     • NEXT_PUBLIC_NOTION_DATABASE_ID：值就是你第二步复制的数据库 ID。
     • NOTION_TOKEN：值就是你第二步复制的secret_令牌。
   • 添加完成后，如下图所示：(注：此为示意图，实际操作界面请以 Vercel 为准)
5. 部署：点击 “Deploy”。Vercel 会开始自动拉取代码、安装依赖、构建项目。整个过程大约1-3分钟。

部署成功后，Vercel 会给你分配一个*.vercel.app的临时域名。点击这个链接，你的 NotionNext 博客就应该已经上线了！如果页面空白或报错，请跳转到本文的“常见问题排查”章节。

3.5 第四步：基础配置与主题切换

博客上线了，但可能还不是你想要的样子。我们需要进行一些基础配置。

1. 修改博客配置文件：

   • 在你的 GitHub 仓库里，找到根目录下的blog.config.js文件。
   • 点击编辑按钮，修改里面的关键配置：

     const BLOG = { AUTHOR: '你的名字', // 博主名 BIO: '你的个人简介', // 首页显示的简介 LINK: 'https://你的博客域名', // 你的博客主域名，暂时可以先写 Vercel 给的域名 KEYWORDS: '博客, 技术, 生活', // 网站关键词 // ... 其他配置 }

   • 提交更改后，Vercel 会自动触发一次新的部署。

2. 切换主题：

   • NotionNext 内置了多个主题（如 Next, Medium, Hexo, Fukasawa）。默认可能是Next主题。
   • 在blog.config.js中，找到THEME配置项，将其值改为你想要的主题名，例如THEME: ‘medium’。
   • 同样，提交更改等待自动部署，或者去 Vercel 控制台手动触发 “Redeploy”。

3. 绑定自定义域名（可选但推荐）：

   • 在 Vercel 项目的 “Settings” -> “Domains” 里，添加你购买的域名（如blog.yourname.com）。
   • 根据 Vercel 的提示，去你的域名注册商（如 Cloudflare, Namesilo, 阿里云）那里添加一条CNAME记录，指向cname.vercel-dns.com。
   • 等待 DNS 生效（通常几分钟到几小时），你的博客就可以通过专属域名访问了。

4. 深度定制与高级功能配置

基础博客搭建完成后，你可以根据自己的需求进行深度定制，让它真正成为你的专属空间。

4.1 页面结构与路由自定义

NotionNext 的页面主要分为两类：

1. 动态路由页面：博客文章详情页，路径由slug决定（如/article/my-first-post）。你无需手动创建，系统自动生成。
2. 静态页面：如首页 (/)、归档页 (/archive)、分类标签页 (/tag/[tag])、关于页 (/about) 等。

如何添加一个自定义页面（例如“作品集”）？

• 在 Notion 数据库里，新建一条记录，Title填“我的作品”，slug填portfolio，type选择Page，status设为Published。
• 然后，在这个 Notion 页面里，用你喜欢的任何方式（文字、图片、画廊、看板等）来构建你的作品集内容。
• 访问https://你的域名/portfolio，这个页面就自动生成了。它的样式由你选择的主题控制。

4.2 评论系统的集成

静态博客需要外接评论系统。NotionNext 支持多种主流方案，我以Giscus（基于 GitHub Discussions）为例，因为它免费、无广告、且与开发者社区结合紧密。

1. 安装 Giscus App：访问 giscus.app ，用 GitHub 账号登录。按照指引，将 Giscus App 安装到你存放博客源码的 GitHub 仓库（授权时选择my-blog仓库）。
2. 配置 Giscus：在 giscus.app 页面上，填写你的仓库名，选择“Discussions”作为来源，设置一个讨论分类（如“Announcements”）。
3. 获取配置：页面下方会动态生成一段<script>配置代码。你只需要复制里面的几个关键数据：>const BLOG = { // ... 其他配置 COMMENT: { GISCUS: { enable: true, // 启用 Giscus repo: ‘yourname/your-repo‘, // 你的仓库，如 ‘tangly1024/NotionNext‘ repoId: ‘R_kgDOJ...‘, // 从 Giscus 获取 category: ‘Announcements‘, categoryId: ‘DIC_kwDOJ...‘, // 从 Giscus 获取 mapping: ‘pathname‘, // 推荐使用 pathname reactionsEnabled: ‘1‘, theme: ‘preferred_color_scheme‘, // 跟随系统主题 } } }
4. 部署后，你的博客文章底部就会出现评论框了。评论数据存储在 GitHub 仓库的 Discussions 中，管理非常方便。

4.3 样式与主题魔改

如果你对前端开发感兴趣，NotionNext 的定制潜力巨大。

1. 主题目录结构：所有主题位于themes/目录下，每个主题一个文件夹（如themes/next）。
2. 核心文件：
   • [theme]/Layout.js：定义了整个页面的骨架结构（Header, Main, Footer）。
   • [theme]/components/：存放各种小组件，如博客卡片 (BlogPost)、导航栏 (NavBar)、页脚 (Footer)。
   • [theme]/styles/：存放全局和模块化的 CSS 文件。
3. 如何修改：
   • 最简单的方式是直接修改你当前使用主题下的组件文件。例如，想修改博客卡片样式，就找到themes/[your-theme]/components/BlogPost.js文件，调整其中的 JSX 和 Tailwind CSS 类名。
   • 如果你想创建一个全新的主题，最好的方式是复制一个现有主题（如next）的文件夹，重命名后进行修改。然后在blog.config.js中将THEME指向你的新主题名。
   • 经验之谈：修改前，先在本地开发环境运行npm run dev，这样你可以实时看到修改效果。使用浏览器的开发者工具（F12）检查元素，能快速定位到需要修改的类名。

5. 常见问题与排查技巧实录

在实际部署和运营过程中，你几乎一定会遇到下面这些问题。我把它们和解决方案整理出来，希望能帮你节省大量时间。

5.1 部署后页面空白或显示“Internal Error”

这是最常见的问题，90%的原因出在环境变量配置上。

• 排查步骤：

  1. 检查 Vercel 环境变量：登录 Vercel，进入项目设置，确保NEXT_PUBLIC_NOTION_DATABASE_ID和NOTION_TOKEN已正确添加，且没有多余的空格。特别注意：NOTION_TOKEN必须以secret_开头。
  2. 检查 Notion 集成连接：回到你的 Notion 数据库页面，点击右上角 “···” -> “Connections”，确保你的集成（如 “My Blog”）在列表中，并且状态是已连接。
  3. 检查数据库ID格式：确保复制的数据库ID是32位十六进制字符串，且没有包含URL中的?v=等参数。
  4. 查看 Vercel 构建日志：在 Vercel 项目的 “Deployments” 标签页，点击最近一次部署，查看构建日志（Build Log）。如果日志中有明显的错误信息（如 “Failed to fetch Notion database”），通常会指向具体原因。

• 我的踩坑记录：我曾因为NOTION_TOKEN复制时末尾多了一个换行符，导致认证失败。在 Vercel 的环境变量输入框里，粘贴后一定要仔细检查末尾是否有不可见字符。

5.2 文章列表为空，但数据库里有文章

• 原因一：文章状态未设置。NotionNext 默认只抓取status属性为Published的文章。请确保你的文章记录中，status列已选择Published。
• 原因二：数据库属性名不匹配。请严格检查你的数据库列名是否为slug,type,status，大小写必须完全一致。type列里，文章必须标记为Post。
• 原因三：Notion API 缓存。Notion API 有短暂的缓存。如果你刚刚在 Notion 里发布文章，可以稍等1-2分钟，或在 Vercel 上手动触发一次 “Redeploy”。

5.3 本地开发环境无法运行

如果你想在本地修改代码并预览，需要搭建开发环境。

1. 克隆你的仓库到本地：git clone https://github.com/yourname/my-blog.git
2. 安装依赖：在项目根目录运行npm install或yarn。
3. 创建本地环境变量文件：在根目录创建.env.local文件，内容如下：

   NEXT_PUBLIC_NOTION_DATABASE_ID=你的数据库ID NOTION_TOKEN=你的Notion令牌

4. 启动开发服务器：运行npm run dev或yarn dev。打开浏览器访问http://localhost:3000。

• 常见错误：如果遇到Module not found错误，通常是依赖安装不完整，删除node_modules文件夹和package-lock.json/yarn.lock文件，重新运行npm install。

5.4 网站访问速度优化

虽然 Vercel 的全球 CDN 已经很快，但仍有优化空间。

1. 图片优化：Notion 中的图片默认通过 Notion 的服务器加载，有时可能较慢。可以考虑：
   • 使用 Next.js 的官方图片组件<Image />，它自带懒加载和优化功能。但需要将 Notion 图片链接代理或下载到自己的存储中，实现较为复杂。
   • 更简单的方案：在写作时，将图片上传到图床（如 Cloudflare Images、Imgur、或国内的可信图床），然后在 Notion 中插入图片链接。这样图片加载速度就和你的博客主机无关了。
2. 减少第三方脚本：检查并移除不必要的分析、广告等第三方 JavaScript 脚本，它们会阻塞页面渲染。
3. 开启 Vercel 的 Edge Functions 或 ISR：对于更新不频繁的页面（如关于页），可以在getStaticProps中设置一个较长的revalidate时间，实现增量静态再生，减轻服务器负担。

5.5 如何更新 NotionNext 版本？

你的仓库是从模板创建的，与上游官方仓库独立。因此，官方更新新功能或修复 Bug 时，你需要手动同步。

1. 将官方仓库添加为远程上游：

   git remote add upstream https://github.com/tangly1024/NotionNext.git

2. 获取上游更新：

   git fetch upstream

3. 合并更新到你的主分支（操作前请备份你的配置和自定义修改！）：

   git checkout main git merge upstream/main

   这个过程可能会产生代码冲突（特别是你修改了主题文件时），需要你手动解决冲突。
4. 推送更新并触发部署：

   git push origin main

   Vercel 会自动检测到main分支的更新并重新部署。

核心建议：对于重要的自定义修改（如主题魔改），建议你通过创建自己的主题文件夹来实现，而不是直接修改themes/next等官方主题。这样在合并上游更新时，冲突会少很多，甚至没有冲突。