Navfolio 博客模板部署&使用完整指南

使用 Navfolio 模版，前置要求：电脑已安装 Node.js 和 Git

一、环境准备 & 项目初始化

1. 安装 Bun

1
curl -fsSL https://bun.sh/install | bash

2. 克隆项目仓库

1
git clone https://github.com/dodolalorc/astro-navfolio.git my-navfolio
2
cd my-navfolio

3. 安装依赖并启动本地服务

1
bun install
2
bun run dev

本地访问地址：http://localhost:4321

二、部署前置小贴士

Tips：别急着修改网站，直接部署上线 Cloudflare Pages（先处理兼容性问题）

• 符合敏捷开发的原则（先上线最小功能，再快速迭代）
• 否则，改好网站，发现环境问题，会非常头大

三、站点基础信息修改

修改站点核心配置，打开文件：src/config/site.toml

• 修改 [config.site] 下的 title（站点标题）和 description（站点描述）
• 修改 [config.profile] 内的个人资料信息

四、提交代码至个人 GitHub

1. 在 GitHub 新建空白仓库

   • 仓库名建议：my-navfolio（和本地文件夹、Cloudflare Pages 项目名保持一致，减少问题）
   • 可设置仓库不公开
   • 不要勾选 README 文件

2. 本地终端执行以下命令关联仓库并推送代码

1
# 关联个人 GitHub 仓库
2
git remote set-url origin https://github.com/你的GitHub用户名/my-navfolio.git
3

4
# 提交代码
5
git add .
6
git commit -m "Initial commit with custom config"
7
git branch -M main
8
git push -u origin main

五、Cloudflare Pages 部署步骤

1. 进入对应功能页

登录 Cloudflare 控制台，点击左侧导航栏 Workers & Pages

2. 创建应用

点击 Create application，选择 Pages 标签页

3. 关联 GitHub 仓库

1. 点击 Connect to Git，授权 Cloudflare 访问你的 GitHub 账号
2. 选中上一步创建的 my-navfolio 仓库
3. 点击 Begin setup

4. 关键：构建设置

进入 Set up builds and deployments 页面，按如下配置：

• Project name：默认即可，也可自定义
• Build command（必填）：bun run build

  重要：该命令会同时触发 Astro 构建和 Pagefind 搜索索引的生成

5. 环境变量

（防坑必看，根据实际需求补充配置）

6. 开始部署

点击 Save and Deploy，Cloudflare 会自动拉取代码并执行构建。 等待1~2分钟，出现绿色成功提示即部署完成，同时会分配免费二级域名：xxxx.pages.dev

六、自有域名绑定（必做）

Tips：默认 pages.dev 域名存在访问限制，建议绑定自有独立域名

1. 进入 Cloudflare Pages 对应项目面板，切换到 Custom Domains 选项卡
2. 点击 Set up a custom domain，按页面提示添加 CNAME 解析记录
3. Cloudflare 会自动配置 SSL 证书与全球 CDN 加速

绑定完成后，后续仅需在本地编写内容，推送代码即可自动更新站点。

七、新建文章 & 命名规范

在项目根目录的终端中，执行对应命令生成内容文件：

1. 新建内容命令

1
# 普通博客文章
2
bun run post:new my-first-post
3

4
# 交互式博客文章 (MDX)
5
bun run post:new my-interactive-post --mdx
6

7
# Vibe 短记录
8
bun run vibe:new today-cloud
9

10
# Vibe 交互式记录 (MDX)
11
bun run vibe:new photo-note --mdx

2. Slug 命名规则

• 命令后跟随的参数（如 my-first-post）为 slug，即网页 URL 路径名，≠ 文章展示标题
• 命名建议：全小写英文、数字、连字符组合（例：my-project-2026），对 SEO 和 URL 更友好
• 目录区分：
  • 博客文件：自动生成至 src/content/blog/
  • Vibe 记录文件：自动生成至 src/content/vibe/，文件自带日期前缀

八、Markdown 格式要求（Frontmatter）

所有博客、文档、独立页面，文件顶部必须添加 YAML 格式元数据（Frontmatter），Navfolio 会做格式校验，格式错误会导致构建失败。

使用脚本新建文件时，该结构会自动生成，无需手动编写。

标准 Frontmatter 模板

1
---
2
title: '文章标题'
3
description: '用于归档页和元信息的简短摘要。'
4
date: '2026-05-28'
5
draft: false
6
heroImage: '/src/assets/figure/example.png'
7
showHeroImage: true
8
tags:
9
  - Astro
10
comments: true
11
sidebar:
12
  enable: true
13
  toc: true
14
  relatedPosts: true
15
---

核心字段说明

• title：网页实际展示的文章标题
• draft：草稿开关。true=仅本地可见、不上线；false=正式发布
• comments：单篇文章评论功能开关
• sidebar：右侧辅助区域配置，可单独控制目录(toc)、相关文章(relatedPosts)是否展示

--- 闭合标签下方，即可使用标准 Markdown / MDX 语法撰写正文。

九、网站内容更新流程

GitHub 仓库与 Cloudflare Pages 绑定后，全程使用 Git 工作流 自动部署：

1. 本地修改：编辑/新增 Markdown 文件，保存改动

2. 本地预览（可选推荐）

   1
   bun run dev

   访问本地地址，确认内容、排版无误

3. 提交并推送代码

   1
   git add .
   2
   git commit -m "Add new blog post: my-first-post"
   3
   git push origin main

4. 自动部署 执行 git push 后，Cloudflare Pages 会实时监听仓库更新，自动执行构建命令。等待约1分钟，新内容、搜索索引会同步上线，无需手动操作控制台。

十、附加配置：关闭 Astro 开发者工具栏

Bun 环境（推荐）

1
bunx astro preferences disable devToolbar

NPM 环境

1
npx astro preferences disable devToolbar

十一、常见问题 & 解决方案

1. 字体工具依赖报错

问题现象：提示缺少 fonttools 依赖，每次云端部署都需要重复安装 原因：Cloudflare 云端为全新部署环境，不会保留本地依赖 解决方案：参考下文「字体优化本地化」，仅在本地完成字体处理，云端不再执行安装命令

2. GitHub 自动新增分支报错

问题现象：Cloudflare 集成/PR 机器人自动推送 cloudflare-workers-xxx 分支，引发配置报错 解决：删除自动生成的异常分支，检查仓库自动化规则，关闭多余的 Cloudflare 仓库集成

3. Astro Session 会话报错

问题现象：提示依赖 SESSION KV 数据库 原因：Astro 开启了 Cloudflare Session 会话功能，依赖 KV 数据库组件

4. 框架&插件版本不匹配

问题现象：升级 Astro 核心框架后，出现组件找不到类错误（如 rehype.js not found） 原因：Astro 主版本升级，但配套官方插件（@astrojs/mdx、@astrojs/cloudflare 等）未同步升级 解决：升级 Astro 后，必须同步升级所有官方插件，保持版本一致

5. 依赖冲突（终极重装方案）

出现玄学依赖问题、构建异常时，执行命令清空依赖并重装：

1
# 1. 删除依赖文件夹、锁文件、缓存目录
2
rm -rf node_modules
3
rm -f bun.lockb bun.lock
4
rm -rf .astro
5

6
# 2. 重新安装纯净依赖
7
bun install
8

9
# 3. 强制升级指定插件（以 MDX 为例）
10
bun add @astrojs/mdx@latest

6. 字体优化本地化（解决云端加载慢、依赖报错）

多数中文主题会使用 Python 脚本切片中文字体，禁止在 Cloudflare 云端执行字体切片，正确流程如下：

1. 项目根目录创建 Python 虚拟环境（Mac/Linux 推荐，避免污染全局环境）

1
# 创建虚拟环境 .venv
2
python3 -m venv .venv
3

4
# 激活虚拟环境（终端前缀出现 (.venv) 即为成功）
5
source .venv/bin/activate

2. 安装字体切片工具

1
pip install fonttools brotli

3. 本地执行构建（自动完成字体切片）

1
bun run build

执行成功后，切片后的字体文件会生成至 public/fonts/ 目录。

4. 退出虚拟环境

1
deactivate

5. 修改 package.json 构建命令（核心） 移除云端多余的安装、切片逻辑，仅保留静态打包：

1
// 修改前（臃肿、易报错）
2
"build": "pip install fonttools brotli && bun run fonts:ui && astro build && pagefind..."
3

4
// 修改后（极简、极速）
5
"build": "astro build && pagefind --site dist --output-subdir pagefind --root-selector main --exclude-selectors \"[data-pagefind-ignore]\""

7. 网页/图片更新不生效（缓存问题）

方案一（最简）

在文章内新增一个空格，重新提交代码推送，触发重新构建。

方案二（清除构建缓存）

1. 登录 Cloudflare 控制台，进入 Pages 项目
2. 切换至 Deployments 标签页，找到最新一次部署记录
3. 点击右侧 ...，选择 Retry deployment → Clear build cache and retry 系统会清空构建缓存，重新编译部署。

方案三（清除全站 CDN 缓存）

1. 进入域名管理页面，左侧选择 Caching → Configuration
2. 在 Purge Cache 区域，点击 Purge Everything 清空全站缓存
3. 等待10秒，浏览器强制刷新页面：
   • Windows：Ctrl + F5
   • Mac：Cmd + Shift + R

十二、附录：高频报错排查宝典

确保它的完整结构如下（重点是新增了 assets 配置）：

1
{
2
  "name": "my-blog",
3
  "compatibility_date": "2026-05-29",
4
  "assets": {
5
    "directory": "./dist"
6
  },
7
  "kv_namespaces": [
8
    {
9
      "binding": "SESSION",
10
      "id": "你的真实KV空间ID"
11
    }
12
  ]
13
}

祝你接下来的每一次 git push，都能换来云端的秒速绿灯！