基于 Astro 搭建个人知识库：从零开始的完整部署指南#

告别平台束缚，用 Astro + Starlight 打造属于自己的知识王国

一、需求分析——你为什么需要“自己的”站点？#

1.1 常见写作场景与痛点#

知识记录这件事，尝试过不少方法。最早用 Word 写，文档越积越多，散落在各个文件夹里，查找全靠记忆。后来接触到语雀等在线笔记工具，用了很久，但公司网络限制加上使用卡顿，体验并不理想。再后来，遇到了 Obsidian——双链笔记、本地存储、体验流畅，确实是非常优秀的笔记工具。但 Obsidian 缺乏在线的能力，知识分享的体验稍微弱了一些。

回顾下来，知识写作有几种典型场景：

• 短内容（博客/随笔） ：需要时间线、标签聚合、RSS 订阅——这是博客类站点的基本功。
• 长内容（书籍/手册/笔记） ：需要目录层级、侧边栏导航、全文搜索——这是文档类站点的核心诉求。
• 两者的冲突：博客主题往往太重（不适合长文档），文档主题又太死板（不适合博客）。

一个理想的知识站点，应该既能承载碎片化的博客随笔，也能容纳体系化的长篇笔记，而且所有内容都属于你自己。

1.2 平台化方案 vs. 自建方案#

平台的写作能力始终有限制。比如后面等 Typst 的 HTML 能力成熟了，就可以让 AI 帮我们开发对应的写作方式——这些在平台上基本做不到。

所以，想要一个自己的站点，可以记录自己写的博客、书籍、笔记。知识如果不能分享，那就太寂寞了。

二、部署方式的选择——服务器 vs. 静态托管#

2.1 两种主流方式对比#

最开始，我在腾讯云上部署了一台服务器跑 Hexo 框架，基本上不用自己费心搭建和管理环境，腾讯云可以一键部署。但是每年需要出小几百块的服务器费用，还是挺麻烦的。

后来了解到静态网站托管服务，才发现——不用花钱，很方便地就可以部署和托管。

2.2 为什么推荐静态托管？#

• 本方案完全生成 纯静态 HTML，无需数据库，无需后端。
• Vercel/Netlify 支持 Git 自动化部署（push 即发布）。
• 国内用户可考虑 Cloudflare Pages（无需备案，自带全球 CDN）。
• Netlify 免费套餐提供 100GB 带宽和 300 分钟构建时长每月。

三、静态网站生成器（SSG）选型指南#

3.1 主流 SSG 一览#

3.2 我们为什么选择 Astro？#

Astro 的主题很丰富，热度很高，很容易找到匹配自己需求的模板。根据 2026 年的 SSG 对比分析，Astro 被认为是内容优先网站的最佳整体选择。

• 官方主题 Starlight：为长文档设计，开箱即用，默认几乎不加载 JavaScript，轻量且快速。
• 社区插件丰富：starlight-blog（博客）、starlight-obsidian（笔记无缝集成）均由同一作者 HiDeoo 维护，生态一致性好。
• AI 友好：官方有专门的 AI 辅助开发指南，生态中已有 AI 深度集成的主题和工具。
• “岛屿架构”（Islands Architecture） ：页面默认是静态的，只有需要交互的部分才加载 JavaScript，性能极佳。默认情况下，所有 Astro 项目都在构建时预渲染为静态 HTML，提供最轻量级的浏览器体验。

四、整体搭建与部署流程（全景预览）#

在开始动手前，我们先了解一下静态网站的工作流程：

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  环境准备    │ ──▶ │  项目初始化  │ ──▶ │  内容写作   │ ──▶ │  本地预览   │
│ (Node.js)   │     │ (Astro CLI) │     │ (MDX/Ob.)  │     │ (npm run dev)│
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                                                                      │
                                                                      ▼
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  持续更新   │ ◀── │  网站上线   │ ◀── │  构建部署   │ ◀── │  Git推送   │
│ (写即发布)  │     │ (公开URL)  │     │ (npm run build)│     │ (git push) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

总耗时预估：首次配置约 30-60 分钟，之后每次写文章只需提交 Git 即可自动部署。

五、详细操作步骤#

我们以 Starlight 主题为例进行详细说明，其他主题类似，只需把 starlight 替换为对应主题名称即可。

5.1 环境准备#

1. 安装 Node.js：推荐 v18 或更高版本。可以在 nodejs.org ↗ 下载安装。
2. 验证安装：打开终端，运行以下命令确认安装成功：

   node -v
   npm -v

   bash
3. （可选）安装 Obsidian：从 obsidian.md ↗ 下载安装，用于本地写作。

5.2 创建项目#

使用 Astro CLI 快速创建 Starlight 项目：

# 创建新项目（使用 Starlight 模板）
npm create astro@latest my-site -- --template starlight

# 进入项目目录
cd my-site

# 安装依赖
npm install

创建完成后，项目结构大致如下：

my-site/
├── astro.config.mjs    # Astro 配置文件
├── package.json        # 项目依赖管理
├── src/
│   └── content/
│       └── docs/       # 📝 所有文档内容放在这里
│           └── index.md # 首页
└── public/             # 静态资源

Starlight 使用基于文件的路由——src/content/docs/ 中的每个 Markdown、MDX 或 Markdoc 文件都会变成站点上的一个页面。

5.3 安装博客插件（starlight-blog）#

Starlight 默认是文档主题，要增加博客功能需要安装 starlight-blog 插件。

npm install starlight-blog

然后在 astro.config.mjs 中配置插件：

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightBlog from 'starlight-blog';

export default defineConfig({
  integrations: [
    starlight({
      title: '我的知识库',
      plugins: [
        starlightBlog({
          // 博客相关配置
          authors: {
            ganlinfei: {
              name: '甘林飞',
              // 其他作者信息
            }
          }
        }),
      ],
      sidebar: [
        // 侧边栏配置
      ],
    }),
  ],
});

博客插件会自动：

• 支持 date、tags、authors 等元数据
• 自动生成 /blog/ 列表页和 RSS 订阅

5.4 安装 Obsidian 集成插件（starlight-obsidian）#

如果你使用 Obsidian 写作，starlight-obsidian 插件可以将本地 Obsidian Vault 映射为网站内容源。注意，该插件由 HiDeoo 维护，与 starlight-blog 为同一作者。

npm install starlight-obsidian

安装 Playwright（如果 Vault 中包含 Mermaid 图表）：

npx playwright install --with-deps chromium

在 astro.config.mjs 中配置：

// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';
import starlightObsidian, { obsidianSidebarEntries } from 'starlight-obsidian';

export default defineConfig({
  integrations: [
    starlight({
      title: '我的知识库',
      plugins: [
        starlightObsidian({
          vault: '../path/to/obsidian/vault',  // ⚠️ 替换为你的 Vault 路径
          output: 'notes',                      // 输出目录名
          ignore: ['**/模板/**', '**/.obsidian/**'], // 忽略的文件
          sidebar: {
            label: '笔记',                      // 侧边栏显示名称
            collapsed: false,                  // 是否默认折叠
          },
        }),
      ],
      sidebar: [
        // 使用 obsidianSidebarEntries 自动生成 Obsidian 侧边栏
        obsidianSidebarEntries(),
        // 其他侧边栏配置...
      ],
    }),
  ],
});

⚠️ 注意事项：

• vault 路径可以是绝对路径或相对路径。
• 插件会从 Vault 中读取所有 Markdown 文件并生成对应的页面。
• 关于首页：如果希望保留 Starlight 漂亮的 Hero 首页，不要删除 src/content/docs/index.mdx，而是在 astro.config.mjs 中配置 output: 'notes'，让笔记内容输出到 /notes 路径下，避免与根路由抢占。如果不需要 Hero 首页，可以删除默认的 index.mdx，在 Vault 根目录创建 index.md 作为首页。

5.5 配置导航与侧边栏#

Starlight 默认会根据文件系统结构自动生成侧边栏。你也可以在 astro.config.mjs 中手动配置。

基本配置示例：

// astro.config.mjs
export default defineConfig({
  integrations: [
    starlight({
      title: '我的知识库',
      sidebar: [
        // 自动生成：根据目录自动生成侧边栏
        {
          label: '指南',
          autogenerate: { directory: 'guides' },
        },
        // 手动链接：指向具体页面
        {
          label: '关于',
          link: '/about/',
        },
        // 分组：可折叠的标题
        {
          label: '教程',
          items: [
            { label: '入门', link: '/tutorials/getting-started/' },
            { label: '进阶', link: '/tutorials/advanced/' },
          ],
        },
        // 外部链接
        {
          label: 'GitHub',
          link: 'https://github.com/your-username',
        },
      ],
    }),
  ],
});

配置说明：

• slug：指向 src/content/docs/ 中的页面
• link：指向特定 URL（内部或外部）
• label：侧边栏显示的标签
• items：分组下的子项目数组
• autogenerate：根据指定目录自动生成

5.6 本地预览与调试#

# 启动开发服务器
npm run dev

启动后，打开浏览器访问 http://localhost:4321，修改内容会自动热更新。

5.7 推送代码到 GitHub（部署前的关键一步）#

在部署之前，需要将代码推送到 GitHub 仓库：

# 初始化 Git 仓库
git init

# 创建 .gitignore 文件，排除不需要提交的目录
echo "node_modules/\ndist/\n.env" > .gitignore

# 添加所有文件并提交
git add .
git commit -m "first commit"

# 关联远程仓库（替换为你的仓库地址）
git remote add origin https://github.com/你的用户名/仓库名.git

# 推送到 GitHub
git push -u origin main

5.8 部署到生产环境#

方式一：Vercel（推荐）#

Vercel 是 JavaScript 框架的默认选择，Astro 集成开箱即用。

1. 在 vercel.com ↗ 注册账号
2. 点击 “Add New Project”，导入你的 GitHub 仓库
3. Vercel 会自动检测 Astro 项目，无需额外配置
4. 点击 Deploy，几分钟后即可访问

构建配置（Vercel 自动识别）：

• 构建命令：npm run build
• 输出目录：dist/

方式二：Netlify#

Netlify 的流程与 Vercel 类似——连接仓库，Netlify 自动检测 Astro 并构建部署。

1. 在 netlify.com ↗ 注册账号
2. 点击 “Add new site” → “Import an existing project”
3. 连接 GitHub 并选择仓库
4. Netlify 自动检测 Astro 配置，点击 Deploy

Netlify 免费套餐：100GB 带宽 + 300 分钟构建时长/月。

方式三：Cloudflare Pages#

适合国内用户，无需备案，自带全球 CDN。

1. 在 pages.cloudflare.com ↗ 注册
2. 连接 GitHub 仓库
3. 框架预设选择 “Astro”
4. 构建命令：npm run build，输出目录：dist/

5.9 内容维护工作流#

在 Obsidian 中写作 → 保存 → git add . → git commit -m "更新内容" → git push → 自动部署

零前端代码，只关注内容本身。每次推送代码到 GitHub，托管平台会自动触发构建和部署。

六、绑定自定义域名#

Netlify/Vercel 默认分配的是 xxx.netlify.app 或 xxx.vercel.app 域名，不太方便访问和分享。如果你有自己的域名，可以绑定。

我之前在腾讯云平台购买过域名 glinfei.space，下面以 Netlify 为例说明两种绑定方式。

6.1 绑定域名的原理#

用户访问 glinfei.space → DNS 解析 → Netlify 服务器 → 返回你的站点内容

核心操作是：让域名解析指向 Netlify 的服务器。

6.2 方案一：添加 CNAME 记录（推荐，最简单）#

这种方式不修改域名注册商的 DNS 服务器，风险最低，操作最简单。

操作步骤：

1. 在 Netlify 中添加域名：

   • 进入 Netlify 项目仪表盘
   • 左侧菜单选择 Domain management
   • 在 Production domains 区域点击 Add a domain
   • 选择 Add a domain you already own，输入你的域名（如 glinfei.space）
   • Netlify 会提示你需要添加 CNAME 记录，并给出一个目标地址（如 glinfei-space.netlify.app）

2. 在腾讯云添加 CNAME 记录：

   • 登录腾讯云控制台，进入 域名管理 → 找到你的域名
   • 点击 DNS 管理 → 添加记录
   • 记录类型选择 CNAME
   • 主机记录填 @（表示根域名）或 www（表示子域名）
   • 记录值填 Netlify 给的目标地址

3. 等待生效：

   • 等待几分钟到几小时（取决于 TTL 缓存），Netlify 会自动签发 SSL 证书，域名即可生效

6.3 方案二：使用 Netlify DNS（全托管）#

这种方式需要将域名的 DNS 服务器完全交给 Netlify 管理，适合需要更精细控制 DNS 记录的场景。

操作步骤：

1. 在 Netlify 设置 DNS：

   • 进入 Domain management，点击 Set up Netlify DNS
   • Netlify 会显示一组 Name Server 地址，格式类似：

   dns1.p01.nsone.net
   dns2.p01.nsone.net
   dns3.p01.nsone.net
   dns4.p01.nsone.net

   plaintext

2. 在腾讯云修改 DNS 服务器：

   • 进入 域名管理 → 找到你的域名
   • 点击 DNS 管理 → 修改 DNS 服务器
   • 将默认的 DNS 服务器替换为 Netlify 提供的四个地址
   • ⚠️ 注意：此操作会清空腾讯云原有解析记录，建议先导出备份

3. 在 Netlify 添加 DNS 记录：

   • 在 Netlify 手动添加 www 等子域名的 A/AAAA/CNAME 记录

4. 等待生效：

   • 域名变更后，一般 几小时到 48 小时 才能完全生效（DNS 全球同步需要时间）

两种方案对比：

七、前瞻：为什么 Astro 是 AI 时代的首选#

7.1 Astro 的 AI 生态#

Astro 在 AI 辅助开发方面走在前列：

• 官方 AI 指南：Astro 官方文档中有专门的 Build with AI 指南，为 AI 辅助开发提供最佳实践。
• AI 就绪的集成：社区已有 astro-webmcp 等集成，可以让你的 Astro 站点一行代码就具备 AI Agent 可读性——AI 代理可以自动发现、搜索和导航你的网站内容。
• LLM 优化：@waldheimdev/astro-ai-llms-txt 可以自动生成 LLM 优化的 llms.txt 文件，让大语言模型更容易消化你的内容。
• AI 技能集成：astro-skills 实现了 Agent Skills Discovery 标准，允许 AI 代理发现和使用你网站上发布的技能。

7.2 Content Layer API：AI 生成内容的天然接口#

Astro 5 引入了 Content Layer API（内容层 API），用可插拔的 Loader 替代了传统的内容集合（Content Collections）。这意味着：

• 内容可以来自任何来源——本地文件、CMS、数据库、API，甚至 AI 生成的内容
• 社区已有 astro-strapi-loader 等 Loader，并专门提供了 AI 辅助的编码指南
• 未来，当 Typst 的 HTML 导出能力成熟后，可以通过自定义 Loader 直接接入 Typst 渲染的内容

7.3 Typst 的未来可能性#

• Typst 0.13 开始实验性支持 HTML 导出
• Typst 0.15 大幅改进了 HTML 导出：数学公式可通过 MathML 原生导出，段落处理更加完善
• 多文件输出功能正在开发中，未来一个 Typst 项目可以同时输出一个 HTML 网站、一份 PDF 报告

Astro 的 Content Layer API 让接入 Typst 变得可行——未来可以编写一个 Typst Loader，直接从 Typst 源文件生成页面，无需中间转换成 Markdown。

八、总结#

从零到一搭建个人知识库，我们完成了：

之后的工作流极其简单：在 Obsidian 中写作 → Git 提交 → 自动部署。

这套方案的核心优势在于：

• 内容自主：所有内容以 Markdown 形式存储，随时可迁移
• 零成本：静态托管免费额度完全够用
• 高效率：写即发布，无需关心运维
• 可扩展：Astro 生态丰富，Content Layer API 让接入 AI 生成内容和 Typst 成为可能

知识如果不能分享，那就太寂寞了。

参考链接#

• Astro 官网 ↗
• Starlight 文档 ↗
• Starlight 手动配置指南 ↗
• Starlight 侧边栏配置 ↗
• starlight-blog ↗
• starlight-obsidian ↗
• Vercel 部署指南 ↗
• Netlify 部署指南 ↗
• Netlify 域名管理 ↗
• Cloudflare Pages 文档 ↗
• Obsidian 官网 ↗
• Typst 官网 ↗