SOLARIS II

如何搭建个人网站

Properties1
tags技术

19分钟阅读

搭建个人网站的方案有很多：有全程不需要花一分钱的，也有付费的；有可定制化程度高的，也有比较傻瓜式省心的……我没有做全面的调研，只是选择了一个自己可以接受的方案——尽可能免费、可接受少量代码、可定制化程度相对较高方便后期美化调整、国内可无压力裸连、支持由Obsidian笔记库直接生成网站。

参考了Nicole van der Hoeven的详细教程，最终我的使用方案是：

Obsidian + Github + Quartz-4 + CloudFlare

以下步骤仅供我自己记录备忘，如有不详尽之处，请参考Nicole的教程。此外AI也是个好用的帮手，遇到不懂的地方，问一问豆包、DeepSeek，或者ChatGPT。Quartz的官方文档也是个有用的参考，不过这个文档不如Nicole的教程简洁明了。

0. 前期准备与软件安装

0.1 必需软件下载安装

  1. Visual Studio Code
    其实VS Code不是必需的，你也可以选择用系统终端和记事本来解决，但我更喜欢在VS Code中完成所有文件的编辑和管理以及终端指令的运行。VS Code的功能不少，你只需要其中的一部分。
  2. NodeJS
    Quartz需要NodeJS才能运行，直接在官网下载安装即可，装好了什么也不用做。
  3. Git
    由于我们需要使用Github来托管我们的网站配置文件以及要在网站上发布的内容，安装Git能够使我们更快捷地使用命令行来从远端拉取仓库以及将本地仓库推送到远端（发布网页！）。同样，按步骤安装，安装好后就暂时不需要进行任何操作了。
  4. Obsidian
    这个不用多说，下载安装即可。我们用它来编辑Markdown文档，我们要在网站上发布的笔记都来自于此。有搭建个人网站需求的朋友，估计很多就是想发布自己在Obsidian的笔记吧。

0.2 新建项目文件夹

在电脑某目录下新建一个空文件夹，并将其重命名为你想要的名称，如my_website。

0.3 简单配置Visual Studio Code

由于只需要用到最基础的功能，所以简单配置界面即可。为了操作方便，可以先将界面调成中文。

设置中文界面

步骤1：在主页面按下Ctrl + Shift + X打开扩展选项卡，搜索简体中文/Simplified Chinese语言包并安装。

步骤2：按下Ctrl + Shift + P打开搜索栏，搜索Configure Display Language并选择简体中文。

在查看中选择终端以打开终端面板，之后的命令行操作都将在这里输入和运行。

在文件菜单中选择打开文件夹，打开在步骤0.2中新建的文件夹my_website。

1. 下载并安装Quartz

1.1 克隆Quartz仓库

安装Quartz并不需要安装包，由于我们已经安装了Git，现在只需要使用命令行工具从远端把Quartz的开源仓库克隆到本地即可。

在VS Code的终端（Terminal）中输入如下指令并按回车执行：

git clone https://github.com/jackyzha0/quartz.git my_website

这个指令将把GitHub上的Quartz库克隆至你的本地文件夹my_website中。

1.2 安装Quartz的依赖库

接下来需要安装Quartz运行所依赖的库（Library），先将操作路径切换至刚刚新建的文件夹my_website：

cd my_website

然后使用NPM来安装库：

npm i

1.3 初始化Quartz

等待库安装完毕，现在新建一个Quartz项目：

npx quartz create

接下来会让你选择创建的方式：

- Empty Quartz
- Copy an existing folder
- Symlink an existing folder

选择第一个Empty Quartz（空项目），程序自动运行，会显示如下字样：

Choose how Quartz should resolve links in your content. You can change this later in `quartz.config.ts`.
- Treat links as absolute path
- Treat links as shortest path
- Treat links as relative paths

这里是让你选择Quartz如何处理笔记内容中的链接，如果你是Obsidian用户，选择Treat links as shortest path即可。

接下来会显示：

You're all set! Not sure what to try next? Try:
- Customizing Quartz a bit more by editing `quartz.config.ts`
- Running `npx quartz build --serve` to preview your Quartz locally
- Hosting your Quartz online (see: https://quartz.jzhao.xyz/hosting)

大功告成。

2. 设置GitHub仓库

2.1 创建一个GitHub仓库

前往GitHub创建一个新的GitHub仓库。如果没有GitHub账号，就注册一个。

具体的方法不过多介绍，点击New Repository，仓库名称填写与文件夹一致的名称（my_website）。仓库的可见性可以选择公开或私有。

公开还是私有？

选择公开库有一定的好处，后续的操作会简单一些，比如每次Git同步时无须输入密码、可以设置网站的评论区等。但是作为网站的内容（包括网站配置文件和网站笔记内容）存储的仓库，如果设置成公开，意味着网络上任何人都可以通过你的GitHub仓库接触到网页底层文件和所有的笔记原文件，可以对其进行复制、下载，甚至复制后任意修改并再次发表。此外，只要知晓你的GitHub仓库地址，任何人都可以访问你还未打算正式发布的草稿文件。

为了更好地保护内容安全，建议仓库设置成私有，并通过SSH密钥来对其进行远程访问，具体方法见下一小节。

此外，创建GitHub仓库时，千万不要勾选Initialize this repository with README file，也不要添加.gitignore，license留空（None）即可。

2.2 生成SSH密钥

打开之前安装Git时自动安装的Git Bash。

可以输入如下代码先检查已有密钥：

ls -al ~/.ssh

如果看到 id_rsa.pub、id_ed25519.pub 等文件，说明已有 SSH 密钥。若没有，继续下一步。

ssh-keygen -t ed25519 -C "your_email@example.com"
  • -t ed25519：指定密钥类型为 Ed25519（推荐，更安全）。
  • -C "your_email@example.com"：注释，建议使用 GitHub 注册邮箱。

终端会提示：

Enter file in which to save the key (/c/Users/you/.ssh/id_ed25519):

直接按Enter选择默认路径。

接着，会提示设置密码：

Enter passphrase (empty for no passphrase):
  • 输入密码（用于保护私钥，建议设置）。
  • 再次确认密码。

生成成功后：私钥（id_ed25519）和公钥（id_ed25519.pub）会保存在 ~/.ssh/ 目录下。

2.3 添加 SSH 公钥到 GitHub

继续在Bash中输入如下代码复制公钥的内容：

# Windows (Git Bash)
clip < ~/.ssh/id_ed25519.pub

登录GitHub并进入SSH设置页面（点击右上角头像 → Settings → SSH and GPG keys），点击New SSH key或Add SSH key。

  • Title：自定义名称（如My Laptop）。
  • Key：粘贴刚才复制的公钥内容（以 ssh-ed25519 开头）。

点击 Add SSH key。

在 SSH keys 列表中应看到刚添加的密钥，说明添加成功。

2.4 测试SSH连接

在Bash中输入：

ssh -T git@github.com

首次连接会提示：

The authenticity of host 'github.com (140.82.114.4)' can't be established. Are you sure you want to continue connecting (yes/no/[fingerprint])?

输入 yes 并回车。

如果看到：

Hi username! You've successfully authenticated, but GitHub does not provide shell access.

说明连接成功。

2.3 修改origin远程

远程（Remote）是你在GitHub中设置好的一个仓库（Repository）名称。此前我们在初始化Quartz的时候已经创建了两个Remote，但是现在我们需要把其中一个改成我们自己的仓库。

在GitHub中，我们已经创建好了自己的仓库，打开仓库后页面显示如下：

HTTPS vs. SSH？

页面中提供了两个选项。由于我们希望创建的是私密仓库，并通过密码来管理每次的更新，因此这里只能选择SSH。

点击右侧图标复制文本栏中的地址git@github.com:ReynoZ/my_website.git。

随后在VS Code的终端中运行如下指令：

git remote -v

终端会返回类似如下字段：

origin  https://github.com/jackyzha0/quartz.git (fetch)
origin  https://github.com/jackyzha0/quartz.git (push)
upstream        https://github.com/jackyzha0/quartz.git (fetch)
upstream        https://github.com/jackyzha0/quartz.git (push)

现在我们运行下面的指令，移除已有的origin远程：

git remote rm origin

然后再重新添加远程：

git remote add origin git@github.com:ReynoZ/my_website.git

得到类似如下的输出：

origin  https://github.com/ReynoZ/my_website.git (fetch)
origin  https://github.com/ReynoZ/my_website.git (push)
upstream        https://github.com/jackyzha0/quartz.git (fetch)
upstream        https://github.com/jackyzha0/quartz.git (push)

设置完成。

2.4 同步修改

在这一小节中，我们尝试将对本地仓库（本地电脑中的my_website文件夹）的修改推送到远程仓库（GitHub上的my_website仓库）中。

运行：

npx quartz sync --no-pull

终端会返回一些文本，并在最后显示绿色的Done!。

刷新刚刚我们复制SSH URL的GitHub仓库页面，页面应该有所变化，显示类似下面的画面：

这意味着你的仓库已经成功同步了修改！从现在开始，每当你运行上面的指令，你在本地所有的修改都将同步到云端的GitHub仓库。

3. 设置Obsidian库

3.1 将Quartz仓库作为Obsidian库打开

设置好了本地和基础的仓库，并解决了他们之间的连接问题，现在我们该着手开始创建真正的内容了！在我的方案中，我们使用Obsidian来创建和维护内容。

下载并安装好Obsidian，运行。Obsidian会询问你打开哪个仓库，我们选择打开本地仓库。

（可选）设置Obsidian

现在你可以花些时间来装点自己的Obsidian仓库了。如果你对Obsidian很熟悉，可以考虑复刻你原有的仓库主题、插件，并通过复制旧仓库的.obsidian/hotkeys.json到新仓库来实现自定义快捷键的迁移；如果你从来没有使用过Obsidian，可以参考网上的一些教程来熟悉用法，根据未来的工作流按照自己的想法来安装插件实现一些功能。

不过不建议一开始就安装一堆插件设置很复杂的功能，下面几个步骤是我个人必做的，供你参考：

  • 选择一个主题
  • 安装必备插件
    • QuickAdd - 强烈推荐，通过设置模板与快捷指令帮助你更快更标准化地创建笔记，让内容更有条理。
    • Linter - 强烈推荐，让笔记的Markdown格式更标准一致。

3.2 创建笔记模板

Quartz的运行需要我们维护好每一篇笔记的属性（properties），笔记属性通常是用YAML语言写在笔记的最开头，这个开头的部分我们称之为Frontmatter。它看起来是这个样子的：

你可以在创建每篇笔记时手动打上Frontmatter的内容，但这样非常麻烦，因此强烈推荐使用模板来实现批量自动化的创建内容。

笔记模板（template）能够让你更快速地创建标准化的笔记文件，配合QuickAdd插件使用体验更佳。在content文件夹下，我们创建一个闲的文件夹并将其命名为templates，我们将在这里储存所有的模板文件。

以最基础的笔记模板为例，它的Frontmatter包含如下字段：

---
title: ""
draft: true
tags:
---

别忘了前往Obsidian的设置—核心插件—模板中设置好模板文件夹的位置。

模板

Obsidian自带模板这个核心插件，你可以仅使用这个自带功能，或者下载更好用的第三方插件来实现更多定制化的效果。

最受欢迎的模板插件可能是Templater，你可以探索一下它的功能。
其次就是上文提到的QuickAdd，它能与原生模板插件或Templater搭配使用，创建新内容更快。

3.3 创建内容

尝试使用你的模板来创建一两篇笔记。

4. 将本地文件链接到GitHub

4.1 本地渲染网页

在将网站发布公开之前，你需要在本地先确认一切正常。我们可以在本地运行Quartz服务器将Markdown文件转换为HTML，并在浏览器中预览网页效果。

在终端中运行如下指令：

npx quartz build --serve

终端会返回如下文字：

Started a Quartz server listening at http://localhost:8080

如果你使用的是VSCode，按住Ctrl键的同时右键单击上面的链接；或者直接在浏览器中输入上面的链接，你就可以在本地浏览器预览网页效果了。

4.2 同步至GitHub

本地验证后，我们来将所有修改同步到GitHub，运行如下命令：

npx quartz sync

这个命令将你所有的修改都推送到远程的GitHub仓库中。

5. 将库发布到网络上

现在你实现了本地创建（build）网页并预览，而且将所有内容都已经同步到了云端的GitHub仓库，但是这些内容依然只是存储在GitHub仓库中，并没有发布到网络上去。最后这一步骤，就是将所有的Markdown文档发布到网络中。

你可以选择使用GitHub Pages来托管发布网页，也可以像我一样直接使用Cloudflare Pages全权托管。

注意

GitHub Pages与Cloudflare Pages是完全独立的托管服务，二选一即可，不要重复配置！

Option A: 通过GitHub Pages托管

GitHub Pages实现发布请参考官方文档或Nicole van der Hoeven的英文教程。

Option B: 通过Cloudflare托管（推荐）

要使用Cloudflare托管，首先你需要创建一个Cloudflare账号。

购买域名

创建账号后，打开Cloudfalre Dashboard，在域名选项卡下找到注册，点击Buy domain，购买一个域名。

Cloudflare支持使用关键字搜索，随后会自动列出符合你关键字或与之相近的可购买域名。显示的域名订阅价格是每年你需要支付的费用，在自己力所能及的范围内选择一个喜欢的域名购买吧！

创建Pages

在Dashboard的构建选项卡下选择计算下拉菜单，并打开Workers和Pages，点击右上角创建应用程序。根据指引创建一个连接到你GitHub仓库的Pages应用程序。

注意

如下指引基于2026年7月26日的Cloudflare Dashboard版本。由于更新，你所看到的创建流程可能并不一致，如有变化，可以参考Quartz的最新文档提供的流程指引和参数。

点击下方“想要部署Pages？”后面的开始使用按钮，并选择导入现有Git存储库

在页面中设置好你的GitHub账户，并选择我们刚才创建的新仓库my_website。

在后面的设置构建和部署页面，参照Quartz官方文档填入如下参数：

设置选项值
生产分支v5
框架预设None
构建命令npx quartz plugin install && npx quartz build
构建输出目录public

最后点击“保存并部署”，Cloudflare会尝试首次部署你的网站。后面你可以尽情在本地创建内容，只需运行npx quartz sync命令，所有的更改都会自动同步到GitHub仓库，随后自动触发Cloudflare的Pages Worker，网站便会实时发布更新了。

关系图谱

反向链接