科技船长 · blog

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

2,395 words 7 min read #Cloudflare Pages#Astro
Categories 软件

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

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

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

1. 安装 Bun

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

2. 克隆项目仓库

Terminal window
git clone https://github.com/dodolalorc/astro-navfolio.git my-navfolio
cd my-navfolio

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

Terminal window
bun install
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. 本地终端执行以下命令关联仓库并推送代码

Terminal window
# 关联个人 GitHub 仓库
git remote set-url origin https://github.com/你的GitHub用户名/my-navfolio.git
# 提交代码
git add .
git commit -m "Initial commit with custom config"
git branch -M main
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. 新建内容命令

Terminal window
# 普通博客文章
bun run post:new my-first-post
# 交互式博客文章 (MDX)
bun run post:new my-interactive-post --mdx
# Vibe 短记录
bun run vibe:new today-cloud
# Vibe 交互式记录 (MDX)
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 模板

---
title: '文章标题'
description: '用于归档页和元信息的简短摘要。'
date: '2026-05-28'
draft: false
heroImage: '/src/assets/figure/example.png'
showHeroImage: true
tags:
- Astro
comments: true
sidebar:
enable: true
toc: true
relatedPosts: true
---

核心字段说明

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

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


九、网站内容更新流程

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

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

  2. 本地预览(可选推荐)

    Terminal window
    bun run dev

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

  3. 提交并推送代码

    Terminal window
    git add .
    git commit -m "Add new blog post: my-first-post"
    git push origin main
  4. 自动部署 执行 git push 后,Cloudflare Pages 会实时监听仓库更新,自动执行构建命令。等待约1分钟,新内容、搜索索引会同步上线,无需手动操作控制台。


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

Bun 环境(推荐)

Terminal window
bunx astro preferences disable devToolbar

NPM 环境

Terminal window
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. 依赖冲突(终极重装方案)

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

Terminal window
# 1. 删除依赖文件夹、锁文件、缓存目录
rm -rf node_modules
rm -f bun.lockb bun.lock
rm -rf .astro
# 2. 重新安装纯净依赖
bun install
# 3. 强制升级指定插件(以 MDX 为例)
bun add @astrojs/mdx@latest

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

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

  1. 项目根目录创建 Python 虚拟环境(Mac/Linux 推荐,避免污染全局环境)
Terminal window
# 创建虚拟环境 .venv
python3 -m venv .venv
# 激活虚拟环境(终端前缀出现 (.venv) 即为成功)
source .venv/bin/activate
  1. 安装字体切片工具
Terminal window
pip install fonttools brotli
  1. 本地执行构建(自动完成字体切片)
Terminal window
bun run build

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

  1. 退出虚拟环境
Terminal window
deactivate
  1. 修改 package.json 构建命令(核心) 移除云端多余的安装、切片逻辑,仅保留静态打包:
// 修改前(臃肿、易报错)
"build": "pip install fonttools brotli && bun run fonts:ui && astro build && pagefind..."
// 修改后(极简、极速)
"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

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

报错现象根本原因解决办法
ModuleNotFoundError: No module named ‘fontTools’云端/本地缺少 Python 字体依赖不在云端安装依赖;本地使用虚拟环境安装依赖并完成字体切片,同步修改 build 命令
KV Namespace already exists [code: 10014]旧版 Astro Cloudflare 适配器 Bug,重复创建 Session 数据库升级核心依赖:bun update astro @astrojs/cloudflare
rehype.js is not defined by “exports”Astro 主版本升级,@astrojs/mdx 插件版本未同步,版本断层强制升级插件:bun add @astrojs/mdx@latest,删除 node_modules 后重新执行 bun install
externally-managed-environmentmacOS 系统保护机制,禁止全局 pip 安装,防止污染系统 Python 环境在项目根目录创建 Python 虚拟环境 python3 -m venv .venv,在虚拟环境内执行 pip 安装
Missing entry-point to Worker script or to assets directory典型的“手动配置覆盖了系统默认行为”导致的连锁反应创建 wrangler.json 文件,配置 assets 目录为 dist ,代码看下方

确保它的完整结构如下(重点是新增了 assets 配置):

{
"name": "my-blog",
"compatibility_date": "2026-05-29",
"assets": {
"directory": "./dist"
},
"kv_namespaces": [
{
"binding": "SESSION",
"id": "你的真实KV空间ID"
}
]
}

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

Comments

Quiet notes for this article.