创建部署一个 Quartz4 网站吧！ • 月微yuewei

说在前面#

部署属于一个自己的 Quartz 4 ↗ 站点并不是一件难事，而且你可以在网上找到不少的教程，我也是参考了其中一两篇然后部署起来的。

我选择使用这个框架是因为：

无后端支持，纯静态的站点，可以直接部署在 Github Pages 或者托管在 Cloudflare Pages 上；原生支持 Obsidian 的链接语法与文件结构（这个对我而言暂时没有什么作用，因为我用 Typora 写作的，但是能够完美支持 Obsidian 就意味着可以很好地支持和渲染 Markdown 语法）。

而且这个框架有完整的开源社区支持、结构清晰、样式也足够现代，也有 SEO 优化，还是很不错的，开箱即用。我的主站用的是 Vitepress，而且用的是一个不错的主题，其实比这个框架还要轻量和精简不少，也有完善的 SEO 优化，效果应该是比这个站点要好不少的，但是奈何 Quartz 4 自带的主题挺漂亮的，我懒得去优化主站的主题了（因为也不错，极简风格我也喜欢），所以就尝试用这个了。

补充：因为个人的一些调整，目前这个网站对应的仓库已经关闭了……

因此我也写一个简单的笔记，来记录一下创建和发布的一些步骤。

准备工作#

首先你需要有：

一台能够正常上网和运行的电脑（MacOS、Windows、Linux 操作系统都可以）
较好的网络环境（用于下载安装 Node.js 和用 NPM 安装需要的包，以及配置 Git）
一个开发用的 IDE（我使用的是 VSCode）

不同操作系统的 Node 安装方式有所区别，一个可能是统一的安装法是从 Node.js 的官网 ↗ 来获取下载的安装包，然后进行安装。如果你不需要进行其他的对版本有特点要求的开发的话，那么这个方法是完全足够的，而且也足够快也直观。不然，你有其他的高级需求，还是建议选择自己平台对应的包管理器进行安装和管理：

具体的安装配置方式可以自行去搜索一下，网上有很多的教程，找一个新一些的就好了。不使用包管理器的方式进行安装一般需要涉及配置环境变量的操作，务必寻得一个详细的教程进行安装，以减少出错的可能性。

同理，对于 Git 的安装，也建议你在网上寻找一个详细、带图且发布时间较新的教程。正确地配置好 Git 有助于我们顺利地通过后续的步骤，降低出现意外情况的可能性。

确认你的 Node.js 版本#

我使用的是 Fnm 来管理我的 Node 版本，Quartz 4 项目对 Node 的版本要求比较高，至少需要 v22.16.0 的版本（官方项目要求如此，社区的第三方分支暂不清楚；而且项目根目录有 .node-version 文件，要求使用 v22.16.0 版本的 Node，如果你的版本比这个高的话，直接删了这个文件或者将其中的 v22.16.0 改成你的 Node 版本避免出现版本问题），在安装配置好 Node 之后，可以在终端用 node -v 命令来查看自己环境当前默认的 Node 版本：

确认自己的 Node 版本满足要求后，我们继续去到下一步。

使用官方的仓库模板#

官方的模板仓库地址为：https://github.com/jackyzha0/quartz ↗

我们直接 Fork 或者使用这个项目作为模板创建一个新仓库，需要先登录自己的 Github 账号再进行操作：

我选择的是 Use this template ，如果你没有什么其他的需求，我建议你也选择这个而不是选择 Fork（一句话总结就是：Fork 是为了给原项目做贡献而创建一个带有完整提交历史的关联副本，而 Use this template 则是用一个全新的、独立的仓库来快速启动一个新项目，且不包含原有的提交历史）。

填写好必要的信息之后就获得了一个属于我们自己的仓库，我们就可以通过 git clone 加上自己的仓库的 Git URL 来将我们的仓库内容拉取到本地进行修改了。

你可以通过上图中显示的绿色的 Code 按钮来获取到你自己仓库的 HTTPS 链接，当然也推荐你使用 SSH 的方式进行 Clone，不过后者需要你事先在自己的电脑上配置好 SSH 密钥，并且将其添加到自己的 Github 账号中完成验证，这样才可以正常使用。这一步如果你有疑问或者不太熟悉，可以暂时跳到此文的 “同步、构建和部署” 部分，或者在线搜索查询相关的资料来获取帮助。

打开项目和配置依赖#

使用自己的 IDE 找到并打开我们上一步 Clone 下来的文件夹，然后在自己的 IDE 中打开终端，确认 Node 的版本无误之后，使用 npm install 命令来安装好需要的依赖包。这里需要注意的是，这个命令需要在项目的根目录下执行，也就是我们 Clone 下来后，进入文件夹后的那个层级。

稍等一段时间，如果网络通畅的话，一般一分钟左右就可以完成包的安装，然后会输出一些提示，一般不是红色，有可能会包含黄色的提示（是一些简单的英文单词，你可以很容易判断是否安装成功，如果没有把握，可以复制后询问 AI）。如果下载很慢或者最后出现了红色的报错信息什么的，建议可以配置一下镜像源，再执行命令：

npm config set registry https://registry.npmmirror.com

bash

上面这个命令是设置 Npm 下载包时，使用的镜像源为淘宝的镜像，这个镜像网站是用的较多的。

如果你需要恢复官方镜像源，可以执行：

npm config set registry https://registry.npmjs.org/

也可以通过 npm config get registry 命令查看当前设置的镜像源信息

如果不想设置镜像源，但是想要在这次安装的时候走一次镜像，可以使用

npm install --registry=https://registry.npmmirror.com

这可以实现仅在当次命令执行的时候修改下载源，而不会修改任何配置。

下载安装完毕依赖包后，如果你觉得不够保险，或者在刚开始没有设置镜像源就进行下载的时候出现了网络问题导致了报错输出，那么你可以重新运行一次新的命令，也可以多运行几次，直到最后提示你没有任何包被添加和修改为止。

开始属于自己的写作#

在处理好上面的步骤之后，应该是可以获得一个和我类似的目录结构的：

我使用的是 VSCode，如果你显示的样式和我的不太一样，不必担心，我是自己添加了一些插件美化过的，只要文件什么的类似即可（这里我说“类似”，是因我不清楚未来官方结构是否会有变动，总之，如果和我的有很大差别，建议阅读官方文档），因我之前看到的一篇写于几个月前的教程，他的文档是写好放在 content 目录下的，但是我在进行写作的时候，文档是放在 docs 目录下的（因此，在后面我使用的启动命令同样也是基于这个目录的）。

没有什么意外的话，建议你也将写好的文章放到 docs 这个目录下（你可以先将这个目录下的文件全部清空，只留下一个 index.md 文件即可，这个 index.md 就是我们网站的首页，你可以在里面写一些话给第一次来到你网站的读者）：

文件夹可以使用中文命名，Quartz 4 能够处理好，但是文章命名建议不要使用中文，会导致意外的后果。可以使用英文大小写、分隔符来进行命名，扩展名都是 .md ，也就是标准的 Markdown 格式（你也可以采用其他的软件进行写作，比如和我一样使用 Typora 也是可以的，如果觉得入正价格太贵，可以去买单设备授权版——有些商家会拆出来单独售卖；至于学习版，这个就靠各自手段了）。

写作随意，只要在最开始添加一些必要的内容即可，官方支持的字段不少，我没有那么多追求，仅用了两个字段：

---
title: 
description: 
---

yaml

第一个是文章的标题，第二个是对这个文章的简要概述。在英文输入法的状态下写好需要的属性字段和冒号之后，不要忘记先打一个空格，再切换到中文输入法状态进行输入，不然可能会导致一些意外的问题。

后面的内容就照常书写即可，为了美观，一级标题建议保留不使用，从二级标题开始，右侧的大纲默认支持显示到三级标题（当然也可以自行修改），因此如果你想要展示文章的大纲，建议不要使用四级标题等标题。

写好内容之后就和平常一样的，比如你使用的是 Obsidian，就将文章在这个 docs 目录下放好，或者和我一样创建个自己喜欢的文件夹，然后将文章放进去就好。Quartz 4 会自动处理好这些内容，并在最后渲染出来的前端界面的左侧规整地展示出来。

然后我们可以在根目录下使用命令 npx quartz build --serve -d docs 来在本地启动一个开发服务器看看效果。在我们使用这个命令后，Quartz 4 会进行一系列的处理，最终给出一个图示的地址，我们可以按住键盘上的 Ctrl 按键（MacOS 上是 Command 按键），然后用鼠标左键点击一下这个链接，就会自动打开浏览器给我们展示出来渲染好的界面：

你可以在界面的左边看到你写好的文章的标题，像往常浏览网页那样用鼠标点一点，就可以跳转到对应的文章，你可以看看显示效果正不正常。如果你的图片是采用和我一样的相对链接插入的方式，并且统一放在对应文章所在目录同一级的 assets 文件夹下的话，那么可能会碰到图片加载失败的问题。因此建议使用图床来管理自己的图片，不但可以避免一些问题，而且也便于其他人浏览（一般情况下，你选择和我一样将图片打包放在一起的话，不使用 CDN 会导致用户在访问你的网站的时候图片加载慢或者加载不出来，比较影响阅读体验。而图床大部分都会采用 CDN 达到更好的图片优化和加载体验）。

但是如果你确定自己需要采用本地相对引用（Typora 和 Obsidian 都接受这样的设置，你可以很轻松地在软件的设置中找到对图片的处理方式，耐心找找然后启用就可以了。启用之后你便可以在写文章的时候和往常一样，直接复制粘贴即可，软件会自己处理好引用）的方式来展示图片的话，你需要修改一下配置文件，这个部分我放在后面会提到。

至此，我们便完成了从设置开发环境到新建项目和添加自己的文章并查看效果的简易流程。

按需修改配置文件#

当我们将自己的文章整齐放好后，我们自然就要考虑修改配置文件以满足我们自己的需求。比如需要将站点默认语言修改为中文，修改网站的标题等等。我自己的修改幅度不大，因此我只能简单讲讲我修改了什么，如果你有更多的额外的修改需要，我建议可以看看官方文档 ↗ 有没有提及到配置的方式，或者你可以借助较为智能的 AI 助手来深入检索和理解这个框架的代码，然后给出合适的修改建议（建议使用 Claude 3.7/4 系列模型，或者 Gemini 2.5 Pro 模型，或者 GPT-4.1 及以上模型来达到更好的效果。辅助插件可以选择 Roocode、Cline、KiloCode，也可以使用 Cursor 等软件或者 Gemini CLI、Claude Code 等工具）。

找到项目目录下的 quartz.config.ts 文件，打开它，然后我们会看到不少代码内容。不用担心，我们仅仅修改其中的一部分代码即可，不会对这个框架造成什么不好的影响，毕竟个性化是我们的追求，而且配置文件本身就是为了让我们进行个性化编辑的。

这个文件中的属性和值的语法是 属性: 值，你会看到不少值的部分是加了一对英文状态的双引号或者单引号的，这个是固定的语法。有些没有加，一般是布尔类型，也就是我们常说的 True 和 False。还有一些用了括号和花括号，甚至是其他的一些奇妙的符号……不用担心，我们只要修改其中的内容就好，那些奇奇妙妙的符号，我们都不要去动它即可（如果你确实无从下手，可以问问 AI，把你需要修改的部分复制发给它，然后告诉它你想要怎么改，AI 一般会给出正确的代码，然后你可以直接粘贴或者按照 AI 的指引进行修改即可。IDE 会智能检查，如果有问题会给出提示，也不用担心看不懂，问问 AI 就好了）。

我修改的属性如下 ~~（你也可以直接访问我的 Github 仓库 ↗，找到我的配置文件，就可以看到我的修改情况）~~：

pageTitle：这个部分的修改会影响网站左上角的显示文字。我将其修改为 Some Notes，所以你可以看到我的网站左上角显示的文字就是这个。
analytics：修改这里可以使用自己需要的网站统计方式，支持的种类不少，包括但不限于 Google 分析、Umami、Bing 分析等。我使用的是微软提供的完全免费的 Clarity 服务，你也可以去官网 ↗ 很轻松地申请属于自己的 ID，然后按照我的样子填写好即可。

analytics: {
  provider: "clarity",
  projectId: "<这里替换为你获取到的 ID，左右两边的尖括号不要保留，只留下 ID 在双引号中即可>",
},

locale：如果你写的是中文站点，那么需要将这个属性的值修改为 zh-CN，如果是英文站点则保持默认的 en-US 即可。其他语言的站点则需要修改为对应的属性，你可以将鼠标移动到前面的属性上面去，IDE 会智能提示可以写的值，填入自己需要的即可。

baseUrl：修改为你打算部署的域名。比如我的这个网站的域名是 notes.134257.xyz，那么我写的就是这个（现在不是了，现在我写的是 notes.yueweix.com ）。
colors：我仅仅调整了浅色和深色模式下的主题色，将浅色主题的白色添加了一些灰度，深色模式主题的黑色添加了一些蓝色，我认为在一定程度上优化了阅读体验，阅读效果柔和了不少。尤其是深色模式，不是那么强烈的黑白对比度，在有些时候可以让我们阅读起来更舒服一些。

colors: {
  lightMode: {
    light: "#f1f1f1ff", 
    lightgray: "#e5e5e5",
    gray: "#b8b8b8",
    darkgray: "#4e4e4e",
    ......
  },
  darkMode: {
    light: "#1b1b1f", 
    lightgray: "#393639",
    gray: "#646464",
    darkgray: "#d4d4d4",
    ......
  },
},

markdownLinkResolution：如果你碰到了我在前文提到的图片是相对引用的方式插入的，Typora 和 Obsidian 都可以正常显示，但是预览网站的时候却无法正常加载的问题的话，则将这个属性值修改为 relative 即可。这个属性在下面部分，往下面翻一翻就可以找到，或者你可以使用 IDE 自带的搜索功能，一般情况下和浏览器的搜索快捷键是一样的，Windows 上是 Ctrl + F 按键，MacOS 则是 Command + F 按键，即可调出来搜索面板，搜索一下这个属性即可找到。

Plugin.CrawlLinks({
  markdownLinkResolution: "relative",
  openLinksInNewTab: true,
}),

我仅仅修改了这些属性，在我看来这些修改已经可以满足我的需求。

除此之外我们需要注意一个叫做 ignorePatterns 的属性，我们可以看到这个属性的默认值是 ["private", "templates", ".obsidian"]，这表明「Quartz 4」在构建的时候会忽略掉这三个文件夹，因此在写作的时候，我们应该避免将需要发布的页面放在 private 和 templates 这两个文件夹下。而 .obsidian 文件夹是假设你用的是 Obsidian 进行写作的，如果你使用 Obsidian 打开了 docs 文件夹开始写作的话，那么 Obsidian 会自动在打开的目录下生成一个这个默认隐藏的文件夹（因为这个文件夹名字的第一个字符是英文的点号，这表明这个文件夹是默认隐藏的，文件也是同理。如果不在操作系统中打开 “显示隐藏的文件” 这个选项的话，默认是不会显示的，但是在 IDE 中无论打不打开那个选项都会显示出来），这个文件夹同样是要忽略的。

我还修改了 quartz.layout.ts 这个文件中的一点点内容：

links ：修改这个影响的是每个页面的最底部显示的内容，我将其简单修改了一下，添加上了我的主站的链接，并且优化了一下原本的前端显示文字。

footer: Component.Footer({
  links: {
    "Home Site": "https://yueweix.com",
    "Theme Github": "https://github.com/jackyzha0/quartz",
    "Theme Discord Community": "https://discord.gg/cRFFHYye7t",
  },
}),

right ：我注释掉了其中的 Component.Graph() 函数。这样我的网站右上角就不会显示关系图谱了，因为我觉得这个对于我的网站而言是多余的。我不是「Obsidian」的高级使用者，我仅仅是简单的写写文章而已。被注释的代码会被忽略掉，因为是给我们人类看的，不是实际的代码，因此我在需要注释掉的内容前面加上注释的语法，也就是两个英文模式下的正斜杠，就可以实现注释。

right: [
  // 移除掉右侧的关系图谱组件
  // Component.Graph(),
  Component.DesktopOnly(Component.TableOfContents()),
  Component.Backlinks(),
],

left ：在这个属性中，我添加了一个框架自带但是默认没有使用的 Component.RecentNotes() 函数，作用是在左侧显示我的最近写的 3 篇文章。建议是将这个函数放在 Component.Explorer() 函数下面一行，这样便可以将最近写的文章显示在左侧目录的下方，同时还使用了 Component.DesktopOnly() 函数包装，确保只在桌面端显示，在手机等移动设备上自动隐藏，避免因移动设备显示空间不足而导致的样式问题。

Component.DesktopOnly(Component.RecentNotes({
  title: "Recent writing",
  limit: 3
}))

afterBody ：我在这个属性后面添加了一些内容，用于启用 Giscus 评论集成，具体的操作步骤可以参考官方文档 ↗，按照教程获取到属于你自己的 ID 等内容之后，就可以参考官方文档下方给出的示例代码来启用自己的文章的评论功能。因为官方文档给出了详细的步骤，我便不在下方给出我自己的代码。

最后我修改了 README.md 这个文件的内容，换成了我自己随便写的一些话。

这个文件中写的内容不会被显示到网站上，而是会显示在我们的 Github 仓库首页的下面，既是给别人看的，也是可以给自己看的。

至此，我们便完成了个性化的设置，让这个框架更加满足我们的要求。

同步、构建和部署#

我们在写好自己的文章和修改好配置文件之后，不要忘记用 Git 进行保存的操作。

这一步可以使用命令行，也可以使用 IDE 给我们提供的图形化界面。但是在进行 Git 之前，我们需要设置好自己的用户名和邮箱，并且先生成好一个 SSH 密钥，绑定到 Github 我们的账户中后，才能进行后续的操作。这些操作在此便不详细展开了，可以自行去搜索一下，网上也是很多详细的教程，找一个新一点的教程一步步配置即可。或者你也可以参考一下我写的《1Password 接管 SSH 验证和 Commit 签名》这篇文章，里面也提及了如何添加 SSH 秘钥到自己的 Github 账号。

配置好必要的信息之后，我们就可以进行 Git 提交了，我们转到 IDE 提供给我们的源代码管理界面，可以看到一些我们修改过的文件（我以 VSCode 为例，如果你使用的是其他的 IDE 或者文本编辑器的话，以你的显示为准）：

其中右边有显示字母：

字母	表示的意思
U	该文件还未被跟踪
D	该文件已被删除
M	该文件有被修改

这里仅仅说明了这三个比较常见的状态，我们可以不必深入理解。

我们只要关心的是这里列出来的文件是否确定是我们修改和删除过的即可，我们可以一个个点击这里列出来的文件，就会在右侧用差异化的方式显示出来我们的修改情况（红色表示删除，绿色表示增加）。检查确认无误之后，我们可以在最上面写一个消息。

这个消息是必须的，对于我们这种个人的项目，我们可以简单写写自己做了些什么即可，或者让 AI 为我们总结生成一个简短的消息就好。

最后我们点击提交，我们的 IDE 就会提示我们还有未暂存的更改，是否要提交，我们直接同意即可。因为我们已经检查过了，所以直接确认。

然后提交按钮会变成同步，我们再次点击一次，稍等片刻（如果网络通畅的话……），我们的这次改动就会同步到我们的 Github 仓库。我们登录自己的 Github 账号然后找到我们在最开始创建的那个仓库，就会发现我们的更改已经同步到云端上了，这样我们就不用担心本地数据保存问题了，因为我们的更改都完完整整保存在云端了。

那么我们便可以在本地开始构建我们的网站。

同样的在项目根目录打开终端（不用担心自己是不是在项目根目录，只要你通过 IDE 打开的文件夹是正确的，那么我们通过最上方的菜单栏直接打开的终端默认就是我们项目的根目录），然后输入命令 npx quartz build -d docs ，稍等片刻，我们就会看到构建完毕的提示：

检查一下我们目录下是不是有个 public 文件夹，我们的构建输出内容都在这个文件夹下面（其实在我们最开始用命令启动开发服务器的时候，这个文件夹就已经生成好了，我们再使用这个构建命令是为了确保这个文件夹下的内容是最新的）。

然后我们右键点击这个文件夹，选择 “在资源管理器中显示” 或者 “在 Finder 中显示” 或者类似的表述。就会弹出我们熟悉的文件管理器界面，然后我们将这个 public 文件夹下的内容全选后通过自己的压缩软件压缩为一个压缩包（其实也可以不压缩，根据个人情况来选择），然后将这个压缩包上传到我们的服务器网站的根目录下解压，保证这些内容都在服务器网站对应的目录下的根目录中即可。

如果你在服务器上使用的是 1Panel 或者宝塔这样的服务器运维面板的话，那么操作起来的流程是类似于下面的步骤的（我以 1Panel 为例）：

登录到你服务器的 1Panel 后台中
确保已经安装好了需要的网站服务
在网站选项卡中新建一个网站
网站类型选择静态站点
保存后点击打开网站目录
然后将压缩包或者不压缩直接将那个目录拖动到上传窗口中，然后点击确认进行上传
上传完毕后，如果上传的是压缩包则右键进行解压，然后删除掉压缩包即可；如果直接是上传了文件夹，那么默认是不需要进行其他操作的，上传完毕即可
访问站点确认无误，左侧证书部分创建一个 Acme 账户用于申请免费证书。然后点击申请证书，选择自己的网站，选择好自己创建好的 Acme 账户然后其他的保持默认（申请方式我一般用 HTTP，你也可以保持默认），最后点击申请，稍等几十秒即可申请成功
重新回到网站选项卡，找到之前创建好的那个站点，进入配置界面，然后在HTTPS这一栏中启用，再在 SSL 选项选择 “选择已有证书”，Acme 账户选择好自己创建好的账户，然后下面的证书会自动匹配我们网站的域名（如果没有可以手动选择正确的），其他的都保持默认，左下角别忘记保存
重新访问我们的网站，发现已经成功配置好 HTTPS 访问

至此，我们便完成了整个流程，你也获得了一个属于自己的 Quartz 4 站点。

最后的部署步骤我仅仅笼统写了个大概，因我目前的 1Panel 版本还是 V1 的，没有升级到 V2，而现在官方默认安装的版本是 V2 的，操作步骤可能和我的有些不同，为了避免出现差错，我便只写了基本流程，推测大体上是差不多的，如果没有把握，可以去找找其他人分享的步骤。

而使用宝塔或者纯自己用 Nginx 或者其他服务的情况，在此也不做补充了，各个平台有所不同，按照平台的要求来即可完成部署。当然你也可以参考官方文档 ↗，文档中详细提供了不少主流的平台的部署方法，如果你有托管或者部署的需求，那么还是建议看一下。

一点补充#

值得一提的是，如果你在自己的服务器上部署好了静态网页，然后接入 CDN 的话，有概率出现在网站中点击文章链接，但是却返回 404 的情况。这个是个有趣的问题，当我们使用静态网站生成器（如 Quartz、Hugo、Jekyll 等）并配合 CDN 时，很容易遇到。

为了美观和简洁，它们在生成页面链接时，会自动省略掉 URL 末尾的 .html 。所以在网站内部的链接是 /notes/my-first-note ，而不是 /notes/my-first-note.html 。而当我们的 CDN 服务器收到一个对 /notes/my-first-note 的请求时，它会忠实地去源站（或者它自己的缓存里）寻找一个叫做 my-first-note 的文件。但实际上，服务器上的真实文件是 my-first-note.html 。因为找不到完全匹配的文件，所以返回 404 Not Found 错误。

所以我们需要在我们的 CDN 请求规则中添加一个 URL 重写规则，让 CDN 收到一个看起来不像文件（比如没有文件后缀）的请求时，在去源站寻找文件之前，自动在请求的 URL 后面尝试加上 .html 。

我采用的规则是（询问 Gemini 2.5 Pro 得到的，仅供参考；我的 CDN 供应商是 EdgeOne）：

先设置两条 And 连接的条件

条件一：
- 匹配类型: URL Path
- 运算符: 正则不匹配
- 值: \.[a-zA-Z0-9]+$
  - 这个正则表达式的意思是：URL 路径不是以 “点+字母/数字” 结尾的。这就能排除掉所有带后缀的文件请求，如 .css, .js, .png 等
条件二:
- 匹配类型: URL Path
- 运算符: 正则不匹配
- 值: /$
  - 这里是用正则不匹配和 /$ 来排除所有以斜杠结尾的目录请求

THEN (那么执行这个操作)：

操作: 选择回源 URL 重写
重写方式：
- 在配置项中，需要将访问的 URI 重写为它自身再加上 .html。通常变量的形式是 ${http.request.uri.path}.html 或类似的写法
- 重写后的 URI 路径：${http.request.uri.path}.html
  - (请查找 CDN 供应商文档或在界面中寻找提示，确认变量名就是 ${http.request.uri.path}.html 或类似的形式)

保存之后便成功解决了这个问题。

同时，如果你也启用了 Giscus 评论功能并且也使用了 CDN 的话，那么可能会出现 Giscus 的样式错误或者加载失败的问题。这个是因为 CORS 跨域策略阻止了 CSS 样式表的加载。简单来说，出于安全考虑，浏览器默认禁止网页从一个域名去请求另一个域名上的资源。要解决这个问题，CDN 服务器需要在返回 dark.css 和 light.css 这些文件时，在 HTTP 响应头中明确地加入 Access-Control-Allow-Origin 字段，并指明允许 https://giscus.app 这个来源访问。

我采用的规则是（同样也是询问 Gemini 2.5 Pro 得到的，仅供参考）：

IF 条件：
- 匹配类型为 URL path 使用 正则匹配 值为 (dark|light)\.css
- 这个规则能够精确地捕获到所有以 dark.css 或 light.css 结尾的 URL 请求，无论它们具体在哪个目录下
操作：
- 修改 HTTP 节点响应头，类型为设置，将 Access-Control-Allow-Origin 的头部值设为 https://giscus.app

保存生效即可。