NotionNext帮助手册

V4.9.4.2

Sat, 11 Oct 2025 00:00:00 GMT

💡

由于Notion数据格式的变化，所有在 2026.4.2 之前部署的站点请升级至最新版本。可以关注此页面，或项目讨论页获取最新动态： https://docs.tangly1024.com/article/latest

https://github.com/tangly1024/NotionNext/issues

💡

最新事件：2026.4.2 Notion再次更新了接口的数据格式，导致旧版站点不可用。NotionNext紧急发布4.9.3.2 版本修复。4.9.3.2伴随部分数据获取的bug，在4.9.4.2版本中修复。

过往事件 2026.2.7

CloudFlarePage静态部署

Mon, 13 Mar 2023 00:00:00 GMT

前言

💡

CloudFlare方案适用于站点访问量大，而文章更新不频繁的用户。

参考haixin的文章《NotionNext建站-cloudflare版》，这里做了优化

部署效果预览

Notion Blog | 一个NotionNext搭建的博客

一个NotionNext搭建的博客

https://cloudflare.tangly1024.com/

❓

CloudFlare版本是静态导出的，不支持实时更新文章，每次更改Notion内容后请手动部署站点。若需要实时动态更新请使用Vercel\Netlify\Zeabur\VPS部署方案。

💡

CloudFlare部署方案，以及其他所有使用静态导出的方案，默认都不支持NotionNext自带的搜索功能，必须集成Algolia插件才能实现全文搜索。详情参考Algolia全文搜索插件获取帮助:

Algolia搜索引擎 | NotionNext帮助手册

NotionNext如何配置Algolia

https://docs.tangly1024.com/article/notion-next-algolia

开始

访问CloudFlarePage

Cloudflare Pages

Build your next application with Cloudflare Pages

https://pages.cloudflare.com/

创建项目

⚠️

注意，2026年新版的Cloudflare 默认引导部署Workers，但是NotionNext目前的代码不支持Workers动态。暂时还是选择使用Pages静态部署：

部署页面底部有个小小的Pages

直接连接git

导入项目

选择分支

分支选择 deploy/cloudflare-support ；

在4.0.9之后的版本中，可以直接使用main分支部署，无需切换分支

配置参数

来到页面下方的构建设置：

构建命令填

环境变量

配置效果如下

配置说明

变量名称	值
NODE_VERSION	18
VERCEL_ENV	production
NOTION_PAGE_ID	{您的Notion页面id}

最后点击保存并部署即可。

完成部署

页面中心会显示您的访问域名

FAQ

部署失败？如果你的构建日志中出现：

可能是CLoudFlare升级环境导致不兼容，解决方法：降级为旧版构建环境，然后点击重试

需要帮助？

如果你的部署异常，没有出现一个绿色的勾，通常是代码修改异常或者配置错误导致，点击右侧的查看详情，获取详细的部署日志：

在构建日志这一栏可以看到所有详细的错误信息，根据错误日志进行排查问题，如果无法自行排查，可以将日志复制或截图，寻求他人帮助。

CloudFlarePage如何绑定自定义域名？

项目主页找到自定义域，找到下方设置自定义域

填写域名并继续

按照要求在域名服务商后台配置一个CNAME转发

CNAME转发示例

点击下方的激活域，由于我使用的域名商本身就是cloudflare，故此步骤只需几秒即可完成验证。

Hooks 触发部署

CloudFlare 支持和Vercel 类似的hooks 功能，后台生成一个调用地址，即可触发站点重新部署，用于更新文件和配置等。

在项目的设置页面，构建栏目下的部署挂钩。点击加号➕新增一个hooks即可

创建挂钩时，要指定你部署的github代码分支，以及随意起一个挂钩名称；

创建后会生成一个webhook链接，点击复制链接保存使用。

需要注意，CloudFlare的hook 和 Vercel 不一样：

Vercel webhook 👉 GET 也行（在浏览器地址栏输入Webhook网址即可简单触发）

Cloudflare Deploy Hook 👉 只允许 POST（更安全）

浏览器访问会提示 method_not_allowed

👉 防止被随便浏览器点一下就触发部署

Windows/Mac/Linux可以用终端命令行输入以下命令触发

当页面显示如下内容，说明已经触发了重新部署

NotionNext开发先导

Sun, 13 Nov 2022 00:00:00 GMT

前言

在进行二次开发之前，您需要了解到：NotionNext本身支持大量的自定义配置，开发之前，请先访问《配置手册》获取帮助、配置您的站点，例如：

blog.config.js 文件中可以修改站点的基础信息、主题、语言、评论插件等核心配置

每个主题下都有一个配置文件config_[theme].js，以便用户配置自己的页面个性化。

NotionNext 代码结构

自定义脚本

NotionNext操作手册中，有关于自定义脚本和样式的引入方式；即：

在/public/js/custom.js /public/css/custom.css 中引入您的脚本，就可以实现任意的页面功能。

在blog.config.js的CUSTOM_EXTERNAL_JS、CUSTOM_EXTERNAL_CSS中也可以引入第三方的脚本。

💡

用这两种方式引入脚本，即使本机上没有安装nodejs等开发环境，也可以直接在浏览器控制台中编写调试。

Notion中自定义JS和CSS

在4.2.0之后的版本中，您可以直接在Notion中指定网页上的样式，以及执行的脚本，只需在NotionConfig中配置GLOBAL_CSS属性以及GLOBAL_JS属性即可，如下图示例：

自行开发

如果上述的配置方式，不能满足您的需要，例如新增组件、深度定制等等。您可以选择在github上发起issue，提出改进页面的建议，或者遵循此教程，进行您的开发之旅。

💡

可选Codespaces云开发，以及本地开发两种方案。

一、云开发(Codespaces)

💡

这是一个可选方案，相比本地开发，您不需要在电脑上安装环境；直接将Github仓库导入到云开发环境，在线编辑即可。 Codespaces是Github官方提供的云开发环境。

导入启动项目

公众号解锁文章

Thu, 05 Sep 2024 00:00:00 GMT

⚠️

OpenWrite停止此项服务，公众号引流的方案失效了，因此以下文章内容已过期。

如何解锁

在阅读文章详情时，默认会隐藏掉一半的文章内容，后半段需要解锁观看。

点击文章底部的“原创不易，完成人机验证，阅读全文“

在弹出的对话框中，可以看到引导提示：在微信中搜索公众号名，或扫码关注公众号

在公众号，点击左下角“验证码”；（或直接在聊天框发送“验证码”）。

公众号会推送一个链接，访问链接即可看到验证码

回到网页中输入验证码，并点击提交即可

💡

目前已支持所有主题，验证码只需要输入一次，即可解锁全站访问。

需要更新到4.7.0的版本之后才支持本功能。

💡

本功能由自动驾驶小白说倾情赞助。

自动驾驶小白说, 输出专业自动驾驶算法教程的开发者社区. 🦈

NotionNext配置说明

💡

在2025-01-19的版本后加入了黄名单配置，设置后只锁定部分文章

在您的Notion配置中心添加以下配置，即可在网页上激活文章验证码解锁功能

配置名	配置值（示例）	说明
OPEN_WRITE_BLOG_ID	3xxxx-1xxxxxxxxxx0-xx4	OpenWrite后台配置的博客ID[`blogId`]
OPEN_WRITE_QRCODE	https://open.weixin.qq.com/qr/code?username=gh_29d5e8d7d648	公众号二维码图片
OPEN_WRITE_NAME	tangly1024	公众号名字，可用于搜索关注
OPEN_WRITE_KEYWORD	验证码	在公众号设置的自动关键词
OPEN_WRITE_BTN_TEXT	原创不易，完成人机检测，阅读全文	【非必填】按钮提示词
OPEN_WRITE_WHITE_LIST	about,example,test	【非必填】白名单，不需要加密的文章slug，英文逗号隔开。全站其余文章都需要验证码。如果只需要个别文章上锁，请使用黄名单功能
OPEN_WRITE_YELLOW_LIST	wechat-offical-account	【非必填】黄名单，优先级最高，开启后只会锁定黄名单中的文章.英文逗号隔开多个。
OPEN_WRITE_VALIDITY_DURATION	1	【非必填】验证一次后，阅读权限的持续时长，单位是“小时”，默认是1小时

要实现这个配置，你需要先注册OpenWrite平台，获取blogId，并且设置一个用于回复的关键词绑定。

配置的ID从哪里来

进入 Open Write 页面：

「配置页面」->「添加博客」

根据提示填写你的信息，之后就会生成整合方案

关键步骤

我们需要记录这里的blogId这个参数，即上图中blogId后面打马赛克的部分。

按照提示需要在公众号后台设置关键词回复。

公众号二维码图片哪里来？

在公众号管理中心，找到并点击“设置”，找到“账号信息”

在账号信息页面，找到“二维码”，然后点击“更多尺寸”

进入更多尺寸的页面，会呈现出常用的二维码尺寸，和建议扫描的距离，根据需要，选择下载，即可获得相应的公众号二维码。

公众号关键词回复如何设置？

公众号后台找到：自动回复→关键词回复→添加回复

参考我的配置如下：

💡

自动回复的内容中，最重要的就是要带上Openwrite后台提供的验证码链接，用户点击此链接后可以获得验证码，示例： blogId=xxxxx">点此链接，获取博客解锁验证码

注意，这里每个人的链接是不同的，特别是blogId这个参数。

参考

OpenWrite官方文档：

博客导流公众号
做最懂自媒体的工具平台
https://openwrite.cn/guide/readmore/readmore.html

Vercel绑定自定义域名

Thu, 17 Feb 2022 00:00:00 GMT

❓
为什么要绑定自定义域名？ vercel默认提供的域名 *.vercel.app 由于滥用已被大陆屏蔽（DNS污染），如果需要在国内能访问到您的站点，请绑定一个新的域名即可
准备一个域名
首先购买自己的域名，您可以选择以下渠道进行购买：
Namesilo
Godaddy
另外您还可以选择从以下平台获取到免费的域名：
eu.org （eu.org是欧盟组织的免费域名；需要英国的用户信息才能注册;）
~~Freenom~~ ~~（目前已逐步停止域名服务）~~
首推Namesilo
我早先在腾讯云购买的域名，但奈何无耻的价格套路，最后选择迁入Namesilo。
💡
套路指那些首年极其便宜，但次年续费很贵的。如 Godaddy，首年 $0.99，次年续费要 102 元人民币，而且隐私保护还需要额外再加 60 元。
NameSilo优点：
价格便宜稳定，无套路
Namesilo 域名本身价格就比较便宜，COM 域名 $8.99/年，除了一个一美元优惠码，基本没有其他大幅度促销活动，域名续费和首年购买价格一致。
Namesilo 价格表：Domain Pricing
💡
填入我的优惠码 tangly1024a 可以享受 1$的优惠。

永久免费的隐私保护
Namesilo 提供永久免费的域名隐私保护，防止别人通过 WHOIS 查询获取域名所有者的个人注册信息。作为对比，Godaddy 的隐私保护是 60 元/年，Namecheap 则是免费提供第一年。
安全性高
支持账户登陆二次验证和 Domain Defender，保护账户和域名安全。登陆、解锁域名等，都可以设置邮件或短信提醒。
支付方便
支持支付宝、Paypal、信用卡等多种方式付款。
Vercel控制台添加域名
在Vercel控制面板中找到Setting→Domains→Add，在这里可以指定当前项目的绑定域名，一个项目可以绑定多个域名。
输入域名,并Add之后，如果看到下图中的提示（Invalid Configuration）👇, 说明域名已经添加，但需要根据提示添加CNAME或Nameserver的方式激活它，图中所示是要在域名后台添加一条CNAME类型的解析，参数名hexo，值为cname.vercel-dns.com。
这里推荐使用CNAME绑定。请按文档后续步骤配置对应的Cname解析。
域名服务商解析CNAME
以下分多个平台举例，配置方法大同小异，只是入口不太一样，我这里主要讲CloudFlare的配置方法
💡
其它服务商的解析CNAME方法，可以参考
腾讯云托管域名

NotionNext项目运行原理

Mon, 18 Nov 2024 00:00:00 GMT

关于本篇
在这里我简单介绍一下NotionNext项目的运行原理，以及Notion、Vercel、NotionNext三者的关系。
关于解决方案
传统的网站建设，可能会用到的方案：
首先：租一台云服务器；
其次：将网站的代码，例如WordPress或自研的网页上传到到服务器中；
然后：在服务器中自行部署一个数据库，或者向云服务商购买一个数据库。
接着：以服务器为核心，运行代码，并从数据库中读取网页数据。
最后：购买一个域名，将域名绑定在这台服务器的ip地址上。
对比
NotionNext的站点本质也是一样的，只是做了元件的替换，即：把服务器、代码、数据库换了别的替代方案。
首先：注册了一个Vercel云平台：主要提供CPU算力、内存空间、操作系统以及运行环境。
其次：注册了一个Github平台：主要提供协同开发、代码存储与版本管理。NotionNext的代码就可以托管在平台进行维护。
然后：注册了一个Notion笔记：将文字、图片等内容存储在笔记中，
接着：以Vercel为核心，从Github中拉取最新版本的代码、编译运行、并从Notion中读取网页数据，按照NotionNext编码的规则展示网页。
最后：将购买的域名，解析到Vercel云平台提供给我们的服务器地址，Vercel负责将域名进一步解析到项目上。

小结
这里我们可以看到，Vercel替代了服务器的概念，Notion充当一个数据库、NotionNext则是核心的代码。
按我的个人习惯来说，之所以选用这种替代方案，取决于三个痛点：
写作：用Notion写笔记的方式来写文章更加舒适而且长远可持续。用公众号编辑、WordPress后台、用第三方博客平台发布页来写文章，要养成习惯太难。用自己的笔记本写东西才能让我不费力，或者用着舒服，这样才有可能做的长久，做的长久，才有可能做得好。
维护：服务器的安全、升级，数据库的备份、维护，需要耗费一些精力；更可怕的是这种折腾服务器的成就感会让人上瘾，你会不断地从搭建服务器、搭建网站的过程中获得”甜头“，从而沉迷于折腾软件技术。
费用：服务器、域名、我只想发布博客文字，有必要那么贵租一年的服务器吗？
工作流程
接下来，看看这个项目的首次安装、运行，与更新、升级配置过程中，发生了哪些事？

首次安装
《Vercel部署NotionNext》这篇教程详细介绍了部署的方法；部署的过程发生了什么呢？

用户首先要复制我的Notion数据库作为模板
Notion充当数据库的角色，所有支持的表头和字段，都已经在NotionNext代码中固定了，如果表头字段不一致，将导致数据无法被正常读取。
用户复制模板的这一过程就相当于在Notion创建了一个属于自己的、NotionNext能识别的数据库。
用户注册Github平台，并且复制一份NotionNext代码
代码是核心，但是如何做到所有用户都能公开拉取到代码，并且还能随时更新代码，甚至一起参与到代码的开发呢？
Github就是一个程序员们最爱的代码协同管理平台，他就类似于腾讯云文档这样的软件，大家都可以参与一个文档的在线编辑，还可以有版本管理的功能，可以记录并回退到任意一个版本中。
注册一个Vercel平台
前面已经解决了代码和数据库的问题，最后就是解决服务器的问题。
登陆Vercel后，你可以选择将代码上传到Vercel平台中进行部署。但Vercel支持一个更强大的功能，就是直接与你的Github仓库建立实时链接。
Vercel将24小时监听你的Github仓库代码，一旦发生更新或改动，它会自行到您的仓库中拉取最新代码，进行打包编译。
从而实现：你无需关注服务器与部署，只要管好自己在Github中的代码即可。打个比方，这时候你是公司的开发人员，只负责代码规则；服务器的运维任务则交给了一个24小时在线的团队管理。
在新版本的NotionNext，绝大部分的代码配置都支持直接在Notion中配置，这样可以实现，你无需关心代码，只要专注在Notion中配置站点，维护文章内容即可。
NotionNext的运作过程
Vercel 云计算运行 NotionNext代码，不断从你的Notion数据库拉取文章，排版成网站。Notion数据发生变化后，网站数据也会跟着改变。若用纯技术的语言来描述可能比较晦涩难懂，我接下来用打比喻的方式来介绍这个项目的工作原理。
NotionNext小店
NotionNext搭建的站点像一个小餐馆，店铺有招牌门头、有来自网络的客流。客人可以看到店铺的门面、进店查看菜单、并选择要点的菜。
店铺与传统餐饮店不同，店里没有烹饪菜品用的厨房，没有专业的厨师。所有菜都是从Notion那边进货的预制菜；Notion是NotionNext店铺唯一指定的供应商、又或者可以称之为中央厨房。
店里有很多“店小二”，店小二是由Vercel云平台提供的CPU、硬盘、内存等构成的员工，他们听从门店的指挥、按照代码设计好的店规流程办事。
店小二主要做以下几件件事：
去Notion进货，在代码中指定了小二要去哪个Notion页面进货（配置NOTION_PAGE_ID）
接客：根据客人点菜时他们将预制菜放进微波炉加热。
将菜品呈在盘子里给客人上菜。NotionNext提供多种盘子的主题、例如Hexo、Gitbook等、店长可以配置选择主题来决定用什么呈现方式交付客户。
节能减排的NotionNext
NotionNext是一个提倡节能减排的店。
店铺首次开张时，会从Notion把每种菜都进一批货，把这批菜品就保存在仓库里(仓库指的是Vercel的硬盘和内存)。
当店里没客人时，店里的员工一动不动；店员不会主动去热菜、不会去进货、也不用招呼客人，甚至店里为了省电都不开灯。
Vercel店员有一个特点，他们都是外包的临时工，或称共享员工。当店里没事情做时，他们会按照Vercel人力资源公司的调度，去到别的店里打工。
当客户通过网站地址访问店铺，需要有人干活时，Vercel会自动在第一时间调人过来帮忙。
上菜流程
若店里来了客人，会发生什么？
客人走进店铺的大门，店里会派出一名小二，扮演跑堂的角色，他们会关注客人的一举一动，例如客人眼睛看向哪道菜，或者手指指向哪道菜，小二都会通过对讲机通知后厨检查库存并提前热菜。同时这个店小二还会按照店长指定的规则，主动向客人展示推荐当季的热门菜。
客人点菜后，上菜流程是怎么样的？
客人径直走进店铺，直接点了首页的某道招牌菜。这时候，跑堂会通知店小二会去仓库里找这道菜，看看是否有没有上次取来的库存：
若有，就先把这道库存菜拿来，检查一下有没有变质，如果在保鲜期许可内，则用微波炉热一下，然后呈在盘子里拿给用户；同时会通知后台派另一个“店小二”，去Notion取一下最新的菜，取回来放在仓库里备用。
若客户点的菜店里没有库存，店铺就会让用户等一会儿，让小二优先加急去取菜，取到了马上给用户热菜、上菜。
那这样用户访问的体验会不会不好？有的上菜慢，有的菜都凉了、或者不新鲜。
关于上菜慢的问题，客户来点菜时，小二会一次性热好几份菜备着，并且设定菜变质和凉掉的时间，例如30秒钟，在这30秒内有新客点这道菜的话，小二不用热菜也可以直接上。超时的菜就要“回炉重造”。
关于菜品不是最新的，小二虽然不会主动去Notion取新菜，但是上个客户来点菜时，店小二会同时去检查有没有新货取来备用。这样后续新客来店里就能刚好吃上最新的菜。
这样设计流程的特点是：客户点的频繁的菜，更新的也勤快；而客户不常点的菜，即使是再新鲜的热菜又有何用？店铺里往往是20%的菜品带来80%的收益，剩下的80%的菜仅仅作为陪衬。
另一方面，若不是资深同行，80%的客人通常品尝不出菜是否新鲜。你肯定觉得老板是奸商、但这就是事实，商人除了考虑口碑，还要考虑成本和效益，在用户能够接受的情况下，尽量降低成本。
这里可以发现，Notion小店的理念不是在追求100分的完美，而是将有限的、80%的精力资源，投入到大概率会发生的，有实用价值的事情中，将整体店铺的体验分数做到80分。
若你研发了一道新菜在Notion里，想让NotionNext店铺的客户第一时间能品尝到要怎么做？
很容易，自己点一单。你自己作为客户，到店里，指名要点那道菜即可，小儿会帮你去备好菜。类似于给自己刷单。另外，还有一种笨办法，就是店铺打烊并重新开张，让小二去重新进货（这就是在vercel后台redeploy的过程）。
更新站点
前面讲到NotionNext这家店的上菜流程，接下来讲讲和Vercel、Notion的合作关系，也就是店铺的升级迭代。店铺开久了，难免想升级装修门面，或者培训员工提升一下工作效率。这时候发生了什么呢？
NotionNext加盟店
比起直营分店，我更喜欢连锁加盟，自己开店不如召集大家一起开店来的有趣。
而NotionNext其实就像是一个连锁加盟品牌。
品牌维护、运营中心都在tangly的中央仓库中，tangly日常负责规划设计NotionNext的工作流程、打造NotionNext旗舰店铺的装修样板。并把这些跑通的流程记录在运营手册，也就是代码中。
⚠️
NotionNext店铺的运营手册指的就是项目的代码。

任何人都可以通过复制手册的方式免费加盟。
当有新版的NotionNext店铺运营手册出来后，其它加盟商可以获取最新的“装修方案”、“员工培训手册”、从而带回去提升自己的门店运营效率。
这时候作为加盟商要怎么升级自己的门店呢？
首先，要获取最新的运营手册，手册在tangly的github仓库中，通过同步代码的方式就可以获取最新的手册。
我们的所有加盟商都享有终生免费更新手册的权益
更新手册的问题
需要注意的是，这时候有的加盟商会更新手册失败，这是因为他们在运营自己的店铺时，对手册做出了一些个性化的修改，从而更加符合自身的运营策略和使用习惯，从而导致合并手册的过程中出现分歧。
这种现象是常见的，毕竟不同地区、口味不同，有的菜谱偏咸，有的菜谱偏甜，不可能一个方案适用所有用户。
通常这里会有几种处理方法；
⚠️
这里的手册比喻的是你的Github代码。
加盟商备份自己的手册，先完全照搬Tangly的手册运营店铺覆盖自己当前的手册、确保店铺能正常运营。然后再按照自己备份的个性化手册，一点点微调新版的手册内容。
资深专业的职业经理人，可以做到一边合并手册，一边核对条款的冲突，直接合并成最终版手册。
请总部过来指导，tangly会根据加盟商自定义手册的方式，为加盟商量身定做出最适合加盟商的版本。
💡
加盟商只需要做好手册的更新，Vercel会自动派店小二来按照手册装修店铺、培训小二。
一些优化的体验
有的加盟商发现，更新手册时遇到很多冲突很麻烦，但是又想定制化，该怎么办？
NotionNext 支持你直接在自己的Notion数据库中定制手册，也就是NOTION_CONFIG。
店小二除了听从NotionNext店铺的规则外，也会从Notion中取来NOTION_CONFIG作为本地化的规则，且它的优先级高于总店的规则。
NOTION_CONFIG中可以支持用户配置自己的装修样式和运行规则，如果不希望再升级店铺时本店手册与总店手册冲突，可以尝试一下。
另外，有的店铺想要自行设计店里的餐盘和门店的样式，我推荐加盟商在手册中，另外创建一个附件，在里面编辑自己的内容，而不要改动现有的手册内容。
这里的附件指的就是，加盟商创建自己的主题文件夹，而不是修改现有主题的内容。例如复制一个hexo主题，然后命名为new主题，然后都在这个new主题里修改即可。又或者重新拉取一个代码分支，所有改动在自己的分支里，从而不影响主分支的自动升级。
最后
感谢您的阅读，文章暂时更新到这里，后面有想到新的内容再更新。