1. 项目概述与核心价值如果你和我一样既想拥有一个完全自主、设计精美的个人博客又不想在服务器运维、数据库管理和复杂的后台开发上耗费大量精力那么 NotionNext 这个项目可能就是为你量身定做的。它本质上是一个“桥梁”将 Notion 这个强大的笔记与知识管理工具变成了一个功能齐全的静态博客生成器。你只需要在 Notion 里像平时记笔记一样写文章NotionNext 就能自动抓取这些内容并生成一个部署在 Vercel 上的高速、现代化的网站。我第一次接触这个方案时最打动我的就是它的“无感写作”体验。我不再需要为了发一篇博客去登录某个平台的后台在简陋的编辑器里折腾格式。我的所有草稿、灵感、成文都自然地沉淀在 Notion 这个我每天都在用的工具里。当我想发布时只需要在 Notion 中把一个页面的状态从“草稿”改为“已发布”或者简单地点击一下 Vercel 的“重新部署”按钮我的博客就自动更新了。这种将内容管理Notion与前端呈现Next.js分离的架构不仅解放了创作者也让博客的访问速度极快因为生成的是静态页面。这个项目适合所有希望低成本、高效率建立个人品牌的内容创作者、开发者、学生或任何有分享欲的人。你不需要是 React 或 Next.js 专家甚至不需要懂命令行按照教程一步步操作也能成功。当然如果你有一定的前端开发基础那么 NotionNext 提供的丰富主题和高度可定制性将给你带来更大的发挥空间。2. 核心架构与方案选型解析NotionNext 的成功关键在于它巧妙地组合了几项当下非常流行且成熟的技术形成了一个稳定、高效且开发者友好的技术栈。理解这个架构能帮助你在后续的定制和问题排查中游刃有余。2.1 为什么是 Next.js Notion APINext.js是这个项目的基石。它是一个基于 React 的框架但提供了两大杀手锏功能完美契合博客需求服务端渲染SSR与静态站点生成SSGNext.js 可以在构建时next build就提前获取 Notion 的数据并生成纯静态的 HTML 文件。这意味着用户访问你的博客时加载速度如同访问一个纯 HTML 页面对 SEO 极其友好。同时它也支持服务端渲染适合需要实时数据的场景但博客这种内容相对固定的场景SSG 是首选。基于文件系统的路由在pages目录下创建一个about.js文件就会自动生成/about路由。这种约定大于配置的方式让博客的页面管理变得非常直观添加一个新页面如作品集、友链只需新建一个文件。Notion API是内容的源头。Notion 官方提供的 API 允许我们以编程方式读取数据库Database和页面Page的内容。NotionNext 的核心工作就是调用这个 API获取你指定的 Notion 数据库里的所有文章每条数据库记录对应一篇博客然后将 Notion 特有的区块Block数据转换成 React 组件可以渲染的格式。这个组合的优势在于它将内容管理和网站渲染彻底解耦。Notion 作为无头 CMSHeadless CMS你享受到了它优秀的编辑体验、版本历史和协作功能而 Next.js 作为前端负责提供极致的访问性能和灵活的前端表现。任何一方的升级或变更对另一方的影响都降到最低。2.2 样式方案Tailwind CSS 的实用性项目选择了Tailwind CSS作为样式方案。这是一个实用优先Utility-First的 CSS 框架。你可能习惯了写.button { padding: 8px 16px; }而在 Tailwind 里你直接在 HTML/JSX 元素上写className“px-4 py-2”。对于博客项目来说这带来了两个巨大好处极高的定制自由度主题开发者可以快速构建出独特的设计而无需担心全局 CSS 的类名冲突。每个样式都是局部的。构建产物极小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 前期准备三样必备品在开始之前你需要准备好以下三样东西缺一不可一个 Notion 账户如果你还没有去 notion.so 免费注册一个。一个 GitHub 账户用于托管你的博客代码。一个 Vercel 账户可以直接用 GitHub 账户授权登录非常方便。3.2 第一步复制模板仓库并初始化这是最关键的一步目的是在你自己的 GitHub 下创建一个 NotionNext 项目的副本。访问官方仓库 https://github.com/tangly1024/NotionNext点击绿色的“Use this template”按钮然后选择“Create a new repository”。重要提示不要直接Fork使用“Use this template”功能会创建一个属于你的、独立的全新仓库与上游仓库脱钩方便你后续自由定制而不会在合并更新时产生冲突。为你的新仓库起个名字比如my-blog选择公开Public然后点击创建。创建成功后将这个新仓库克隆到你的本地电脑如果你打算做代码定制或者直接进入下一步。对于大多数只想快速建站用户可以跳过本地克隆完全在云端操作。3.3 第二步在 Notion 中创建数据库并获取密钥你的博客文章都将存储在一个 Notion 数据库里。我们需要创建这个数据库并让 NotionNext 有权限读取它。创建数据库在你的 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封面图链接等。一个标准的数据库视图如下所示Titleslugtypestatusdatetags我的第一篇文章my-first-postPostPublished2023-10-27教程,Notion关于我aboutPagePublished--获取数据库ID在 Notion 中打开你刚创建的数据库。浏览器地址栏的 URL 类似于https://www.notion.so/yourworkspace/a0a1b2c3d4e5f67890123456789abcdef?v...a0a1b2c3d4e5f67890123456789abcdef这一长串字符就是你的数据库 ID。把它复制下来。创建集成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 去构建和部署你的博客。登录 Vercel用 GitHub 账号登录 vercel.com 。导入项目点击 “Add New…” - “Project”你会看到 GitHub 中你刚创建的my-blog仓库点击 “Import”。配置项目Framework Preset: Vercel 会自动检测为 Next.js保持默认即可。Root Directory: 保持默认./。Build and Output Settings: 保持默认。配置环境变量最关键的一步在环境变量配置区域点击添加。你需要添加以下两个变量NEXT_PUBLIC_NOTION_DATABASE_ID值就是你第二步复制的数据库 ID。NOTION_TOKEN值就是你第二步复制的secret_令牌。添加完成后如下图所示(注此为示意图实际操作界面请以 Vercel 为准)部署点击 “Deploy”。Vercel 会开始自动拉取代码、安装依赖、构建项目。整个过程大约1-3分钟。部署成功后Vercel 会给你分配一个*.vercel.app的临时域名。点击这个链接你的 NotionNext 博客就应该已经上线了如果页面空白或报错请跳转到本文的“常见问题排查”章节。3.5 第四步基础配置与主题切换博客上线了但可能还不是你想要的样子。我们需要进行一些基础配置。修改博客配置文件在你的 GitHub 仓库里找到根目录下的blog.config.js文件。点击编辑按钮修改里面的关键配置const BLOG { AUTHOR: 你的名字, // 博主名 BIO: 你的个人简介, // 首页显示的简介 LINK: https://你的博客域名, // 你的博客主域名暂时可以先写 Vercel 给的域名 KEYWORDS: 博客, 技术, 生活, // 网站关键词 // ... 其他配置 }提交更改后Vercel 会自动触发一次新的部署。切换主题NotionNext 内置了多个主题如 Next, Medium, Hexo, Fukasawa。默认可能是Next主题。在blog.config.js中找到THEME配置项将其值改为你想要的主题名例如THEME: ‘medium’。同样提交更改等待自动部署或者去 Vercel 控制台手动触发 “Redeploy”。绑定自定义域名可选但推荐在 Vercel 项目的 “Settings” - “Domains” 里添加你购买的域名如blog.yourname.com。根据 Vercel 的提示去你的域名注册商如 Cloudflare, Namesilo, 阿里云那里添加一条CNAME记录指向cname.vercel-dns.com。等待 DNS 生效通常几分钟到几小时你的博客就可以通过专属域名访问了。4. 深度定制与高级功能配置基础博客搭建完成后你可以根据自己的需求进行深度定制让它真正成为你的专属空间。4.1 页面结构与路由自定义NotionNext 的页面主要分为两类动态路由页面博客文章详情页路径由slug决定如/article/my-first-post。你无需手动创建系统自动生成。静态页面如首页 (/)、归档页 (/archive)、分类标签页 (/tag/[tag])、关于页 (/about) 等。如何添加一个自定义页面例如“作品集”在 Notion 数据库里新建一条记录Title填“我的作品”slug填portfoliotype选择Pagestatus设为Published。然后在这个 Notion 页面里用你喜欢的任何方式文字、图片、画廊、看板等来构建你的作品集内容。访问https://你的域名/portfolio这个页面就自动生成了。它的样式由你选择的主题控制。4.2 评论系统的集成静态博客需要外接评论系统。NotionNext 支持多种主流方案我以Giscus基于 GitHub Discussions为例因为它免费、无广告、且与开发者社区结合紧密。安装 Giscus App访问 giscus.app 用 GitHub 账号登录。按照指引将 Giscus App 安装到你存放博客源码的 GitHub 仓库授权时选择my-blog仓库。配置 Giscus在 giscus.app 页面上填写你的仓库名选择“Discussions”作为来源设置一个讨论分类如“Announcements”。获取配置页面下方会动态生成一段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‘, // 跟随系统主题 } } }部署后你的博客文章底部就会出现评论框了。评论数据存储在 GitHub 仓库的 Discussions 中管理非常方便。4.3 样式与主题魔改如果你对前端开发感兴趣NotionNext 的定制潜力巨大。主题目录结构所有主题位于themes/目录下每个主题一个文件夹如themes/next。核心文件[theme]/Layout.js定义了整个页面的骨架结构Header, Main, Footer。[theme]/components/存放各种小组件如博客卡片 (BlogPost)、导航栏 (NavBar)、页脚 (Footer)。[theme]/styles/存放全局和模块化的 CSS 文件。如何修改最简单的方式是直接修改你当前使用主题下的组件文件。例如想修改博客卡片样式就找到themes/[your-theme]/components/BlogPost.js文件调整其中的 JSX 和 Tailwind CSS 类名。如果你想创建一个全新的主题最好的方式是复制一个现有主题如next的文件夹重命名后进行修改。然后在blog.config.js中将THEME指向你的新主题名。经验之谈修改前先在本地开发环境运行npm run dev这样你可以实时看到修改效果。使用浏览器的开发者工具F12检查元素能快速定位到需要修改的类名。5. 常见问题与排查技巧实录在实际部署和运营过程中你几乎一定会遇到下面这些问题。我把它们和解决方案整理出来希望能帮你节省大量时间。5.1 部署后页面空白或显示“Internal Error”这是最常见的问题90%的原因出在环境变量配置上。排查步骤检查 Vercel 环境变量登录 Vercel进入项目设置确保NEXT_PUBLIC_NOTION_DATABASE_ID和NOTION_TOKEN已正确添加且没有多余的空格。特别注意NOTION_TOKEN必须以secret_开头。检查 Notion 集成连接回到你的 Notion 数据库页面点击右上角 “···” - “Connections”确保你的集成如 “My Blog”在列表中并且状态是已连接。检查数据库ID格式确保复制的数据库ID是32位十六进制字符串且没有包含URL中的?v等参数。查看 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 本地开发环境无法运行如果你想在本地修改代码并预览需要搭建开发环境。克隆你的仓库到本地git clone https://github.com/yourname/my-blog.git安装依赖在项目根目录运行npm install或yarn。创建本地环境变量文件在根目录创建.env.local文件内容如下NEXT_PUBLIC_NOTION_DATABASE_ID你的数据库ID NOTION_TOKEN你的Notion令牌启动开发服务器运行npm run dev或yarn dev。打开浏览器访问http://localhost:3000。常见错误如果遇到Module not found错误通常是依赖安装不完整删除node_modules文件夹和package-lock.json/yarn.lock文件重新运行npm install。5.4 网站访问速度优化虽然 Vercel 的全球 CDN 已经很快但仍有优化空间。图片优化Notion 中的图片默认通过 Notion 的服务器加载有时可能较慢。可以考虑使用 Next.js 的官方图片组件Image /它自带懒加载和优化功能。但需要将 Notion 图片链接代理或下载到自己的存储中实现较为复杂。更简单的方案在写作时将图片上传到图床如 Cloudflare Images、Imgur、或国内的可信图床然后在 Notion 中插入图片链接。这样图片加载速度就和你的博客主机无关了。减少第三方脚本检查并移除不必要的分析、广告等第三方 JavaScript 脚本它们会阻塞页面渲染。开启 Vercel 的 Edge Functions 或 ISR对于更新不频繁的页面如关于页可以在getStaticProps中设置一个较长的revalidate时间实现增量静态再生减轻服务器负担。5.5 如何更新 NotionNext 版本你的仓库是从模板创建的与上游官方仓库独立。因此官方更新新功能或修复 Bug 时你需要手动同步。将官方仓库添加为远程上游git remote add upstream https://github.com/tangly1024/NotionNext.git获取上游更新git fetch upstream合并更新到你的主分支操作前请备份你的配置和自定义修改git checkout main git merge upstream/main这个过程可能会产生代码冲突特别是你修改了主题文件时需要你手动解决冲突。推送更新并触发部署git push origin mainVercel 会自动检测到main分支的更新并重新部署。核心建议对于重要的自定义修改如主题魔改建议你通过创建自己的主题文件夹来实现而不是直接修改themes/next等官方主题。这样在合并上游更新时冲突会少很多甚至没有冲突。