基于 Next.js + Notion 搭建个人网站：nextjs-notion-starter-kit 配置、部署与源码原理全解析

前端【免费下载链接】nextjs-notion-starter-kitDeploy your own Notion-powered website in minutes with Next.js and Vercel.项目地址https://gitcode.com/gh_mirrors/ne/nextjs-notion-starter-kit点击查看免费下载本文以 readme.md 为骨架结合本仓库源码完整讲解如何用 Notion 作为 CMS、借助 react-notion-x 与 Next.js 在几分钟内搭建并部署一个高性能个人博客/作品集网站。读完本文你将掌握site.config.ts全量配置项、Vercel 部署注意事项、URL 路径映射机制、LQIP 预览图与 Redis 缓存、自动社交分享图、自动目录与暗色模式等功能的配置方法并能理解其背后的源码实现。一、项目概览与技术栈nextjs-notion-starter-kit 是一个以Notion 作为 CMS内容管理系统的 Next.js 网站起步模板。作者用它驱动了自己的个人博客与作品集站点核心能力包括只需几分钟完成初始化所有配置集中在一个文件site.config.ts借助 react-notion-x 提供对 Notion 内容的健壮渲染支持基于 Next.js TypeScript React 构建出色的页面加载性能与平滑的图片预览自动生成社交分享图Social Images自动生成美观的 URLPretty URLs自动生成文章目录Table of Contents完整支持暗色模式通过 CMDK / CMDP 快速搜索针对不同设备尺寸的响应式设计针对 Next.js 与 Vercel 做了优化从 package.json 可以看到当前仓库的技术栈与版本next^16.2.0、react^19.2.4、react-notion-x与notion-client/notion-types/notion-utils均为 ^7.10.0、lqip-modern^2.2.1、fathom-client^3.4.1、posthog-js^1.362.0、react-tweet^3.3.0、rss^1.2.2等。构建工具链方面使用了pnpmpackageManager: pnpm10.29.3见 package.json 与 pnpm-workspace.yaml。注意README 中建议 Node.js 版本 16但以当前仓库 package.json 的engines字段为准要求Node 20请按此准备本地环境。二、快速起步从 clone 到上线官方建议的启动流程如下见 readme.md 的 Setup 章节Fork / clone 本仓库修改 site.config.ts 中的若干配置项安装依赖npm install使用 pnpm 则可执行pnpm install本地开发npm run dev部署到 Vercelnpm run deploy等价于vercel deploy核对 Vercel 项目设置详见下文「Vercel 部署配置」相关脚本定义在 package.json 中dev对应next devbuild对应next buildstart对应next startdeploy对应vercel deploy。2.1 获取根页面 IDrootNotionPageId这是整个项目唯一必需的核心配置。操作步骤建议在 Notion 中复制官方提供的默认示例页面作为起点你可以在 Notion 中复制任一公开页面结构无强制要求确保你的根 Notion 页面已设置为公开Public复制该页面的链接提取 URL 末尾形如7875426197cf461698809def95960ebf的一段这就是页面的Notion ID填入rootNotionPageId。在 lib/config.ts 中rootNotionPageId会经过parsePageId(..., { uuid: false })解析如果解析失败会直接抛出Config error invalid rootNotionPageId所以该值必须是合法 ID。2.2 获取工作区 IDrootNotionSpaceId可选如需将站点限制为仅包含单个 Notion 工作区的页面可设置rootNotionSpaceId。获取方式在浏览器中打开你站点的任意页面打开开发者控制台访问全局变量block即当前页面的 Notion 数据输入block.space_id即可打印出工作区 ID。这个变量在 components/NotionPage.tsx 中注入客户端渲染时会将pageId、recordMap、block挂到window全局对象上方便调试。工作区校验则在 lib/acl.ts 中完成——如果页面所属空间与site.rootNotionSpaceId不一致会返回 404 错误社交图接口的校验见 pages/api/social-image.tsx。2.3 内容组织建议官方建议在首页设置一个 NotionCollection集合/数据库用来集中存放所有文章、项目等内容。不过仓库对 Notion 工作区结构没有任何约束你完全可以按照平时习惯自由组织内容。三、site.config.ts 全量配置详解所有配置都集中定义在 site.config.ts其类型定义位于 lib/site-config.ts。下面按类别完整列出可配置项配置项类型必填说明rootNotionPageIdstring✅ 必填站点根 Notion 页面 IDrootNotionSpaceIdstring \| null可选限制页面所属 Notion 工作区namestring✅ 必填站点名称domainstring✅ 必填站点域名生产环境 URL 基址authorstring✅ 必填作者名称descriptionstring可选Open Graph 描述默认Notion Bloglanguagestring可选站点语言默认en用于 RSS feedtwitter/github/linkedinstring可选社交账号页脚与 meta 标签使用newsletter/youtube/zhihu/mastodonstring可选更多社交入口mastodon是完整的 profile URL会换算为 handle 用于链接验证defaultPageIconstring \| null可选全站默认 Notion 图标默认nulldefaultPageCoverstring \| null可选全站默认封面图默认nulldefaultPageCoverPositionnumber可选封面图定位默认0.5isPreviewImageSupportEnabledboolean可选是否启用 LQIP 预览图默认trueisTweetEmbedSupportEnabledboolean可选是否启用推文嵌入isRedisEnabledboolean可选是否用 Redis 缓存预览图默认falseisSearchEnabledboolean可选是否启用站内搜索默认trueincludeNotionIdInUrlsboolean可选URL 中是否包含 Notion ID默认跟随isDevpageUrlOverridesPageUrlOverridesMap \| null可选将指定 Notion 页面 ID 映射到自定义路径pageUrlAdditionsPageUrlOverridesMap \| null可选补充路径映射不覆盖默认路径navigationStyledefault \| custom可选导航风格默认defaultNotion 原生样式navigationLinksNavigationLink[]可选自定义导航链接需配合navigationStyle: custom其中navigationLinks的每个元素支持titlepageId站内页面或titleurl外部链接两种形式。示例配置已注释在 site.config.ts。3.1 配置读取与默认值机制lib/config.ts 是站点级配置的总装车间它从site.config.ts读取原始配置并补充默认值description默认Notion Bloglib/config.tslanguage默认enlib/config.tsdefaultPageCoverPosition默认0.5lib/config.tsisPreviewImageSupportEnabled默认false注意site.config.ts中显式设为true因此默认仓库行为是开启预览图的lib/config.tsincludeNotionIdInUrls默认取isDev的值即开发环境为true、生产环境为falselib/config.tsisSearchEnabled默认truelib/config.tsisRedisEnabled除配置项外还可通过环境变量REDIS_ENABLED开启lib/config.ts此外lib/get-config-value.ts还提供了一层环境变量覆盖机制可通过NEXT_PUBLIC_SITE_CONFIG传入 JSON 形式的配置片段它会与site.config.ts做浅合并spread覆盖lib/get-config-value.tsgetRequiredSiteConfig则会在缺少name/author/domain等必填项时抛出Config error: missing required site config value ...异常。3.2 路径映射的校验逻辑pageUrlOverrides/pageUrlAdditions的值在 lib/config.ts 中会经过cleanPageUrlMap校验页面 ID 必须能被parsePageId解析否则抛错Invalid ... page id路径不能为空且必须以/开头写入后内部会去掉开头的/校验通过后会被整理为「路径 → pageId」的映射同时生成反向映射inversePageUrlOverrides供页面渲染时查询。四、Vercel 部署配置关键官方特别强调默认情况下社交预览图在 Vercel 上无法正常工作原因是站点需要登录鉴权。必须从 Vercel 项目设置中关闭鉴权Project - Settings - Deployment Protection禁用 Vercel Authentication。如果你忘了这一步爬虫以及任何请求社交图的客户端在抓取/api/social-image时会收到401 Unauthorized响应导致分享卡片无法生成。五、URL 路径机制开发与生产的差异项目的 URL 路径在开发与生产环境下默认不同不过将任一环境的路径粘到另一环境通常也能正常解析开发环境使用/nextjs-notion-blog-d1b5dcf8b9ff425b8aef5ce6f0730202这种「标题 slug Notion ID」的形式。开发时始终把 Notion 页面 ID 放在 URL 中便于调试。生产环境使用/nextjs-notion-blog这种更简洁的形式去掉多余的 ID 噪音。5.1 底层实现该机制由 lib/map-page-url.ts 实现mapPageUrl根据includeNotionIdInUrls默认跟随isDev决定是否在 slug 中附加 UUID根页面始终映射为/其余页面通过getCanonicalPageIdlib/get-canonical-page-id.ts生成路径——该函数优先返回pageUrlOverrides的反向映射结果否则回退到 react-notion-x 的getCanonicalPageId默认实现。在构建阶段lib/get-site-map.ts 会调用getAllPagesInSpace抓取空间内所有页面并据此构建canonicalPageMapslug → pageId 映射。其中有一个细节如果页面在 Notion 中显式设置了Public属性且为假则该页面会被从站点地图中排除lib/get-site-map.ts。5.2 按页面覆盖 slug你可以通过在 Notion 数据库中为页面添加一个Slug文本属性来覆盖默认生成的 slug——任何带有Slug属性的页面都会使用该值作为其 URL 路径。注意如果工作区内存在多个同名 slug 的页面构建时会抛出「duplicate URL pathnames」错误开发模式下会先打印error duplicate canonical page id警告见 lib/get-site-map.ts。5.3 请求解析与 URI 缓存当浏览器请求/some-slug时lib/resolve-notion-page.ts 按以下顺序解析先尝试把rawPageId直接当作 Notion 页面 ID 解析parsePageId失败则查询pageUrlOverrides/pageUrlAdditions映射仍未命中则查询数据库Redis/内存中缓存的uri-to-page-id:${domain}:${environment}:${rawPageId}映射该缓存当前不设 TTL最后回退到getSiteMap()的canonicalPageMap查表命中后会把「URI → pageId」写入缓存以加速后续请求全部未命中则返回 404注意404 结果不会被缓存。5.4 关于旧链接官方提醒如果你计划随时间修改页面标题需要确保旧链接仍然有效。本项目目前不提供旧链接检测方案建议借助 Next.js 内置的redirects 支持在next.config.js中配置来处理。六、图片预览LQIP与 Redis 缓存站点使用next/image高效地提供图片服务并可通过lqip-modern生成预览图片LQIP低质量图片占位实现平滑的图片加载体验。预览图默认开启但由于生成过程较慢可通过在 site.config.ts 中设置isPreviewImageSupportEnabled: false关闭。6.1 源码实现lib/preview-images.ts 是预览图的核心模块通过getPageImageUrls收集页面内所有图片 URL并追加默认图标/封面以concurrency: 8的并发度用p-map批量处理每个 URL 先用ky拉取图片二进制再交给lqip-modern生成originalWidth、originalHeight、dataURIBase64三个字段组成的PreviewImage使用p-memoize做进程内记忆化缓存避免重复计算。生成后的preview_image映射会挂到 recordMap 上见 lib/notion.ts最终由NotionRenderer的previewImages属性消费components/NotionPage.tsx。6.2 用 Redis 缓存加速后续构建如果希望把生成的预览图缓存下来、加速后续构建需要先准备一个外部 Redis 数据存储在 site.config.ts 中设置isRedisEnabled: true设置环境变量REDIS_HOST与REDIS_PASSWORD指向你的 Redis 实例。本地开发可添加.env文件REDIS_HOSTTODO REDIS_PASSWORDTODO从源码看Redis 相关变量还支持更多扩展REDIS_URL、REDIS_USER默认default、REDIS_NAMESPACE默认preview-images以及REDIS_ENABLED见 lib/config.ts。底层使用keyvhq/corekeyvhq/redis封装lib/db.ts启用 Redis 时以redisUrl作为存储后端未启用时退化为内存 Keyv 实例。预览图和 Redis 缓存都是可选功能。如果不想处理它们直接在站点配置中关闭即可。官方推荐的 Redis 提供商如 Redis Labs 免费套餐可以自行评估不强制。七、样式定制所有针对 Notion 内容的自定义 CSS 都位于 styles/notion.css。这些样式主要覆盖 react-notion-x 导出的全局 CSS 类react-notion-x/styles.css在 pages/_app.tsx 中全局引入。从仓库源码可以看到一些典型的定制手法styles/notion.css.notion { --notion-max-width: 720px; --notion-header-height: 54px; } .index-page { --notion-max-width: 900px; }即普通文章页最大宽度 720px首页根页面放宽到 900px。每个 Notion block 都有唯一的类名因此可以精确地针对单个块做定制例如.notion-block-260baa77f1e1428b97fb14ac99c7c385 { display: none; }全局样式导入顺序见 pages/_app.tsx依次为 KaTeX数学公式、Prism代码高亮、react-notion-x 核心样式、站点全局样式、Notion 样式覆盖、Prism 主题覆盖。八、暗色模式项目完整支持暗色模式可通过页脚Footer中的太阳/月亮图标切换。实现细节lib/use-dark-mode.ts 基于fisch0920/use-dark-mode使用classNameDark: dark-mode切换按钮在 components/NotionPageHeader.tsx页头与 components/Footer.tsx页脚均有实现当处于暗色模式时NotionPage会给 body 添加dark-mode类components/NotionPage.tsx并同步更新meta nametheme-colorcomponents/PageHead.tsx。九、自动社交分享图Social Images所有 Open Graph 与社交 meta 标签都由 Notion 内容自动生成让社交分享默认看起来专业。社交图通过Vercel OG Image Generation自动生成默认的 React 模板位于 pages/api/social-image.tsx可以按需调整。9.1 生成机制接口以 Edge Runtime 运行export const runtime edgepages/api/social-image.tsx通过?idpageId查询参数指定页面缺省时使用rootNotionPageId使用next/og的ImageResponse渲染1200×630的分享图pages/api/social-image.tsx字体为仓库内置的 Interlib/fonts/inter-semibold.ts图片元素取自页面属性Social Image→ 页面封面 → 站点默认封面作者头像取自页面图标 → 默认图标作者取自Author属性 → 站点authorpages/api/social-image.tsx对于 Unsplash 图片还会自动附加w1200fitmax参数以获取合适尺寸pages/api/social-image.tsx。9.2 前端 meta 输出components/PageHead.tsx 输出完整的 meta 集合og:type、og:site_name、og:description、twitter:card有图时为summary_large_image、twitter:creator、canonical URL、RSS alternate 链接等对于博客文章isBlogPost还会注入BlogPosting类型的 JSON-LD 结构化数据强化 SEOcomponents/PageHead.tsx。社交图 URL 由 lib/get-social-image-url.ts 构造为/api/social-image?idpageIdRSS feed 中也会将社交图作为每条文章的enclosure图片附件输出pages/feed.tsx。十、自动目录Table of Contents默认情况下每篇博客文章页都会在桌面端以aside形式展示目录使用scrollspy滚动侦测逻辑用户滚动文档时自动高亮当前章节并支持点击跳转如果页面标题数量少于minTableOfContentsItems默认3目录自动隐藏目录在首页index page以及浏览器窗口过小移动端时也会隐藏。相关代码目录开关与阈值在 components/NotionPage.tsxshowTableOfContents !!isBlogPost、minTableOfContentsItems 3传入NotionRenderer后由 react-notion-x 渲染侧栏组件为 components/PageAside.tsx。10.1 侧栏的差异化展示components/PageAside.tsx 的展示策略很有意思仅对博客文章isBlogPost展示「推文操作区」Like / Retweet 快捷按钮见 components/PageActions.tsx底层是 Twitter/X 的 Web Intents其他页面展示社交链接components/PageSocial.tsx。其中推文的嵌入数据由 lib/get-tweets.ts 预先抓取并缓存含 Redis 缓存与p-memoize双层缓存渲染时通过react-tweet展示components/NotionPage.tsx。十一、响应式设计所有页面都针对常见设备尺寸做了响应式适配见 styles/notion.css 中的媒体查询与components/styles.module.css。桌面端展示目录侧栏移动端自动收起导航栏在窄屏下可横向滚动。十二、站点分析Analytics分析功能是可选特性按需开启12.1 Fathom AnalyticsFathom 提供轻量级的 Google Analytics 替代方案。只需添加环境变量NEXT_PUBLIC_FATHOM_ID即可启用——仅在生产环境生效。从源码看lib/config.ts 中fathomId在isDev时为undefined并带有excludedDomains: [localhost, localhost:3000]配置pages/_app.tsx 中执行Fathom.load并在每次路由切换完成时调用Fathom.trackPageview()。12.2 PostHog AnalyticsPostHog 提供轻量级、开源的 Google Analytics 替代方案。只需添加环境变量NEXT_PUBLIC_POSTHOG_ID即可启用——同样仅在生产环境使用。实现见 lib/config.ts 与 pages/_app.tsxposthog.init 路由切换时posthog.capture($pageview)。十三、环境变量总览如果需要使用 Redis、分析或其他依赖环境变量的功能需要将这些变量添加到 Vercel 项目Project Settings - Environment Variables。汇总如下环境变量作用说明REDIS_HOSTRedis 主机地址启用isRedisEnabled后必需REDIS_PASSWORDRedis 密码启用isRedisEnabled后必需REDIS_URL完整 Redis 连接串可选优先于HOST/PASSWORD拼接REDIS_USERRedis 用户名可选默认defaultREDIS_NAMESPACERedis key 命名空间可选默认preview-imagesREDIS_ENABLED强制开启 Redis可选等价于isRedisEnabled: trueNEXT_PUBLIC_FATHOM_IDFathom 站点 ID仅生产生效NEXT_PUBLIC_POSTHOG_IDPostHog 站点 ID仅生产生效NEXT_PUBLIC_SITE_CONFIGJSON 配置覆盖与site.config.ts合并需合法 JSONNOTION_API_BASE_URLNotion API 基址传入NotionAPI构造lib/notion-api.ts在 GitHub Actions 中测试 Redis 构建需要编辑.github/workflows/build.ymlREADME 提及当前镜像仓库未包含该目录为构建步骤添加REDIS_HOST与REDIS_PASSWORD并同时在 GitHub 仓库的 Settings - Secrets 中配置对应的 repository secrets。十四、附带的站点能力搜索、RSS 与 sitemap除 README 主线功能外仓库还内置了若干开箱即用的能力均可在配置中控制站内搜索CMDK / CMDP由isSearchEnabled控制默认true。前端 lib/search-notion.ts 以 10 秒过期缓存 POST 到/api/search-notionpages/api/search-notion.ts 仅接受 POST响应带Cache-Control后端转发给 Notion 搜索接口lib/notion.ts。RSS Feedpages/feed.tsx 基于rss包生成 XML遍历站点地图中属于根页面 collection 的博客文章输出标题、链接、描述、日期与社交图附件缓存 24 小时。Sitemappages/sitemap.xml.tsx 根据canonicalPageMap生成sitemap.xml缓存 8 小时。404 / 错误页components/Page404.tsx 与 pages/404.tsx、pages/_error.tsx 处理未找到与异常场景配图位于 public/404.png、public/error.png。lite模式URL 带?litetrue时渲染精简版页面用于 oEmbed 嵌入场景components/NotionPage.tsx。动态导入代码高亮Prism 支持 30 语言、Collection、公式KaTeX、PDF、Modal、Tweet 均为按需动态加载components/NotionPage.tsx。十五、许可证与贡献本项目采用MIT许可证见 license作者为 Travis Fischer。贡献者请参阅 contributing.md。小结nextjs-notion-starter-kit 用一份site.config.ts收敛了绝大多数配置配合 Notion 的公开页面与集合组织内容即可快速搭建个人博客/作品集。理解 lib/config.ts 的默认值策略、lib/map-page-url.ts 的 URL 映射、lib/preview-images.ts 的 LQIP 流水线以及 pages/api/social-image.tsx 的 OG 图渲染能让你在自定义站点时做到心中有数、按需取用。赞分享前端【免费下载链接】nextjs-notion-starter-kitDeploy your own Notion-powered website in minutes with Next.js and Vercel.项目地址https://gitcode.com/gh_mirrors/ne/nextjs-notion-starter-kit点击查看免费下载相关推荐WSABuilds PowerShell脚本Install.ps1源码解析Windows 11安卓子系统自动化安装指南WSABuilds PowerShell脚本Install.ps1源码解析Windows 11安卓子系统自动化安装指南 WSABuilds项目中的PowerS开发工具10分钟上线Notion网站Next.js Notion Starter Kit全流程指南10分钟上线Notion网站Next.js Notion Starter Kit全流程指南 你是否曾想拥有一个个人网站却被技术门槛劝退还在为内容管理系统C前端如何用 Next.js Notion Starter Kit 快速搭建现代网站完整指南如何用 Next.js Notion Starter Kit 快速搭建现代网站完整指南 Next.js Notion Starter Kit 是一个功能强大的前端创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考