一、项目结构概览​

Fblog/
├── .github/workflows/deploy.yml   # GitHub Pages 自动部署工作流
├── blog/                          # 博客文章（Markdown）
├── src/                           # 首页与自定义组件、主题 CSS
├── static/                        # 静态资源（含 CNAME）
├── docusaurus.config.js           # 站点配置（url / baseUrl / 导航等）
├── sidebars.js
├── package.json
├── .gitignore
└── DEPLOY.md                      # 本文档

二、部署前置条件​

• 已安装 Node.js 18+（工作流使用 Node 20）。
• 已拥有 GitHub 仓库 https://github.com/名称/Fblog.git（分支 main）。
• 已配置自定义域名 域名（或准备改用 GitHub 默认域名）。

三、本地提交（最关键的一步）​

而 Docusaurus 源码（blog/、src/、docusaurus.config.js 等）和部署工作流是未跟踪状态。 必须先提交，否则 GitHub 上干净的 checkout 缺少 package.json / docusaurus.config.js， 工作流里的 npm ci / npm run build 会直接失败。

在 Fblog/ 根目录执行：

# 暂存：旧文件删除 + 新 Docusaurus 源码 / 配置
# （.gitignore 已自动排除 node_modules、build、.docusaurus、.workbuddy）
git add -A

# 提交
git commit -m "重构为 Docusaurus 并接入 GitHub Pages 自动部署"

# 推送到 main，触发自动部署
git push origin main

四、GitHub 仓库设置​

1. 打开仓库 Settings → Pages。
2. Source（构建与部署来源） 选择 GitHub Actions（不要选 “Deploy from a branch”）。
3. Custom domain 填写 域名：
   • 项目已在 static/CNAME 写入该域名，GitHub 会自动识别并在每次部署后保留。
   • 首次填写后点击 Save，GitHub 会发起域名所有权验证（需在 DNS 处加一条记录，见下一步）。

五、域名 DNS 配置​

在域名服务商（如 Cloudflare、阿里云、腾讯云）处，为 域名 添加以下任一方式：

方式 A：A 记录（推荐）

方式 B：CNAME 记录

若不使用自定义域名，可跳过本节，改用 GitHub 默认地址（见第七节）。

六、等待部署完成​

1. 推送后进入仓库 Actions 标签页，查看 Deploy to GitHub Pages 工作流。
2. 包含两个 Job：build（构建 Docusaurus）→ deploy（发布到 Pages），均变绿即通过。
3. 浏览器访问 域名 查看站点。

以后只要向 main 分支推送改动（新文章、配置调整等），就会自动重新构建并部署，无需手动操作。

七、自定义域名 vs GitHub 默认域名​

当前 docusaurus.config.js 已按自定义域名配置：

url: 'https://域名',
baseUrl: '/',

注意：baseUrl 必须与访问路径一致。用项目仓库路径时若仍写 /，站内资源（CSS/JS/图片）会出现 404。

八、本地开发与预览​

npm install        # 安装依赖（首次或依赖变更后）
npm start          # 本地开发预览，带热更新，默认 http://localhost:3000
npm run build      # 生成静态文件到 build/
npm run serve      # 预览生产构建（build/）

九、常见问题​

• 工作流失败：npm ci 报错 / 找不到 package.json 说明仓库没有提交 Docusaurus 源码（仍在跟踪旧静态站）。回到第三节重新 git add -A + commit + push。

• 部署后样式/图片 404 通常是 baseUrl 与访问路径不匹配，检查第七节配置。

• 自定义域名访问提示“不安全 / DNS 未生效” DNS 记录未生效（通常几分钟到几小时），或 GitHub Pages 自定义域名验证未通过，确认第五节记录正确且已保存 Custom domain。

• 想彻底不用 GitHub Actions，改用分支部署 不推荐。Docusaurus 官方已弃用 npm run deploy（基于 gh-pages 分支）方式，GitHub Actions 更稳定且无需本地 token。

十、常用命令速查​

最后更新：2026-07-31 · 适用于 Docusaurus 3.10.2 + GitHub Pages（GitHub Actions 部署）

项目开源地址：https://github.com/GuyZeus/A-Nav，仓库仅使用 HTML 编写，轻量化无依赖，打开即用，适合当作浏览器专属首页。

为什么要自己写导航站？​

日常上网一直使用商用导航主页，但 hao123、360导航这类平台广告弹窗繁多、页面臃肿，充斥大量无关推荐链接，每次打开都要被冗余内容干扰。

市面上开源导航模板大多基于 Vue、React 等框架，配置繁琐，对于只想简单收藏网址的需求来说过于沉重。于是决定从零手写一套极简导航页面，只保留自己常用的网站链接，干净无广告，完全自定义。

整个 A-Nav 仅使用原生 HTML 开发，没有引入 CSS、JS 外部依赖，仓库结构极简，仅包含首页 index.html 与图标资源文件夹，代码量少、加载速度极快，手机电脑都能自适应展示。

A-Nav 项目设计思路与功能​

1. 极简干净的页面结构​

摒弃繁杂分区、资讯模块，页面只保留分类网址卡片布局，按照开发工具、学习网站、社区、工具站点做分组，鼠标点击即可跳转对应链接，视觉清爽无多余元素。

2. 轻量化零依赖​

不引入任何第三方库、CSS框架、JS脚本，单页面完成全部功能，仓库体积极小，GitHub Pages 部署秒加载，低带宽环境也能流畅打开。

3. 完全私有自定义​

所有网址、分类名称、图标都可以直接修改 index.html 内代码，按需增删链接，只留存自己高频访问的站点，打造专属个人上网主页。

4. 开源可复用​

项目完全开源，无版权限制，任何人 Fork 仓库后修改链接就能搭建属于自己的导航页，适合前端新手学习静态页面基础布局写法。

GitHub Pages 部署流程（项目仓库型站点）​

和个人主页仓库 用户名.github.io 部署逻辑略有区别，项目类仓库部署步骤如下：

1. 创建普通公开仓库：仓库名自定义为 A-Nav，无需遵循特殊命名规则，上传导航站全部源码文件，确保根目录存在 index.html。
2. 进入仓库配置 Pages：打开仓库 Settings → Pages，部署分支选择 main，部署目录选择根目录 root。
3. 等待自动构建发布：保存配置后 GitHub 自动构建，1分钟左右部署完成。
4. 访问项目在线地址：访问地址格式为 用户名.github.io/仓库名，我的导航站地址为 guyzeus.github.io/A-Nav。

开发与部署踩坑记录​

• 项目站点路径问题：项目仓库部署后页面资源会带上二级路径，图标、图片本地正常线上失效，统一使用相对路径 ./ 引用静态资源即可修复。
• 仓库权限限制：私有仓库无法开启免费 Pages 服务，必须将仓库设置为 Public 公开才能正常部署。
• 缓存更新延迟：修改代码推送后页面不更新，强制 Ctrl+F5 清除浏览器缓存，或等待5分钟左右 GitHub 缓存刷新。
• 移动端布局错乱：初期未添加 viewport 适配，手机端页面缩放异常，头部补充移动端视口 meta 标签后完美适配。

后续优化计划​

目前基础导航功能已经稳定可用，后续会持续迭代升级：

• 增加明暗主题切换功能，适配白天/夜间浏览；
• 加入简易搜索框，快速检索站内收藏网址；
• 优化响应式布局，完善平板、手机端卡片排版；
• 新增本地存储功能，支持自定义网址本地保存，不用修改源码；

写在最后​

这次手写 A-Nav 导航站，不仅解决了日常上网的实用需求，也巩固了原生 HTML 页面布局基础。依托 GitHub Pages 免费静态托管，不用服务器、不用域名成本，几分钟就能上线可用网站。

如果你厌烦了广告满天飞的商用导航，或是想练习基础前端页面开发，都可以 Fork 我的 A-Nav 仓库，修改成属于自己的极简导航主页，低成本打造专属上网工具✨。

区别于第三方企业邮箱、免费邮箱，这套系统完全自主可控，只用一个域名即可批量生成无数个子邮箱，个人注册、验证码接收、日常收发邮件全部自给自足。

为什么要自建 Cloud-Mail 邮箱系统？​

日常使用公共邮箱存在不少痛点：Gmail、QQ邮箱容易收到垃圾邮件，临时注册网站不想暴露个人主邮箱；付费企业邮箱年费成本高，批量创建别名邮箱限制多。

市面上开源邮箱方案大多需要 VPS、邮件服务器、反解析配置，运维复杂。而 Cloud-Mail 基于 Cloudflare Workers 开发，全程无服务器，依靠 Cloudflare 免费额度就能满足个人长期使用需求，完美解决低成本自建邮箱的需求。

技术栈分工清晰：Vue3 + Element Plus 做前端页面展示，Hono 作为 Workers 后端框架，搭配 D1 数据库、KV缓存、R2对象存储，整套代码结构规范，二次开发门槛低。

Cloud-Mail 核心功能一览​

• 多域名批量邮箱：绑定自有域名，无限生成 xxx@你的域名 临时邮箱、长期邮箱；
• 完整收发邮件：集成 Resend 实现邮件发送，支持附件、图片、群发；收件自动存入系统，支持草稿、星标、归档分类；
• 附件存储：使用 Cloudflare R2 存储所有邮件附件，无流量扣费；
• 消息推送：新邮件自动转发至 Telegram 机器人或备用邮箱，实时提醒；
• 管理员后台：RBAC权限管控，管理所有用户、限制收发额度、查看系统数据；
• 开放API接口：支持批量创建账号、接口查询邮件，可对接自己的其他项目；
• 安全防护：内置 Turnstile 人机验证，防止恶意批量注册垃圾账号；
• 个性化自定义：自定义登录页背景、网站标题、界面透明度；配套ECharts数据看板，查看收发邮件统计数据。

项目整体架构​

1. mail-worker（后端服务）​

部署在 Cloudflare Workers，负责邮件接收、接口处理、数据库读写、权限校验；依赖 D1 存储用户与邮件数据，KV做登录缓存，R2存放附件。配置文件 wrangler.toml 统一管理所有云资源绑定信息。

2. mail-vue（前端网页）​

Vue3 响应式管理后台，电脑、手机自适应布局，登录后可查看收件箱、发邮件、修改个人配置、查看数据统计，打包后静态资源可通过 GitHub Pages / Cloudflare Pages 托管。

完整部署流程​

方案：Cloudflare 原生部署（推荐，完整邮件功能）​

1. Fork 本仓库到自己 GitHub 账号；
2. Cloudflare 后台创建 D1 数据库、KV命名空间、R2存储桶，记录所有ID；
3. 注册 Resend 并验证域名，获取发送邮件 API Key；
4. 仓库 Settings → Secrets，填入 Cloudflare 账号ID、API令牌、域名列表、JWT密钥等参数；
5. 开启仓库 Actions，自动构建部署 Workers 后端；
6. 前端 Vue 打包上传至 Cloudflare Pages，绑定域名访问邮箱后台。

部署踩坑记录​

• 云资源绑定丢失：项目代码更新重部署后，D1/KV/R2绑定会失效，需要重新在 Workers 设置中绑定资源，执行初始化接口同步数据库；
• 域名邮件解析失败：域名必须在 Cloudflare 托管，配置对应 Email DNS 记录，否则无法接收外部邮件；
• 静态资源路径异常：GitHub Pages 二级子仓库部署前端时，打包需要配置二级基础路径，否则页面样式、接口请求全部404；
• JWT密钥泄露风险：密钥不能硬编码进代码，必须存放于仓库Secret，否则他人可伪造登录管理员账号；
• 免费额度限制：Cloudflare 免费版 Workers、D1、R2 有每日限额，大量收发邮件会触发限流，个人轻度使用无压力。

后续迭代规划​

• 完善多语言国际化，优化中文界面细节；
• 增加邮件过滤规则，自动拦截垃圾邮件；
• 优化移动端交互，适配小屏手机操作；
• 简化一键部署脚本，降低新手配置难度；
• 增加邮件导出、批量删除功能。

写在最后​

Cloud-Mail 是继手写博客、A-Nav导航站之后，又一个完全自主部署上线的云原生项目。全程依托免费云平台，不用服务器、不用长期付费，就能拥有完全私有化的邮箱服务，不管是注册各类网站收验证码，还是日常工作邮件都非常实用。

如果你厌烦了公共邮箱的广告与隐私泄露问题，又不想花钱购买企业邮箱，不妨 Fork 这份 Cloud-Mail 项目，搭配自己的域名搭建专属私有邮件系统，低成本打造完全属于自己的云服务工具✨。

没有使用成熟的博客框架，也没有复杂的搭建流程，全程靠 HTML + CSS + JavaScript 手写打磨，依托 GitHub Pages 免费托管，从零实现了属于自己的专属个人博客。从页面布局、样式美化到交互调试、线上部署，一步步踩坑、优化、完善，看到域名成功打开页面的那一刻，所有的熬夜折腾都变得格外有意义。

为什么选择手写静态博客？​

市面上的博客搭建方案五花八门，Hexo、VuePress、Jekyll 等框架开箱即用，一键部署十分便捷，但我始终觉得少了一点专属感。

作为前端爱好者，一直想拥有一个完全由自己掌控的博客站点。不用受制于框架的模板限制，不用适配繁杂的配置项，从每一行代码、每一个页面样式、每一个交互效果都由自己定义。

这次全程手写 HTML+CSS+JavaScript，不仅是搭建一个博客，更是一次完整的前端实战练习。从页面自适应布局、样式配色搭配，到简单的动态交互、页面加载优化，全程自主调试，既能沉淀技术，又能打造独一无二的个人展示空间，用来记录学习笔记、技术心得、日常感悟再合适不过。

我的博客部署方案：GitHub Pages​

本次博客最终选择 GitHub Pages 作为托管平台，最核心的优势就是 免费、稳定、零服务器成本、部署便捷，非常适合个人静态博客、作品集网站展示。

不同于需要购买服务器、配置环境的传统部署方式，GitHub Pages 专门用于托管静态网页资源，完美适配纯前端手写的静态站点，无需复杂的后端配置，只要有静态页面文件，即可快速上线。

极简部署流程（纯静态页面通用）​

记录一下本次完整的部署步骤，方便后续复盘，也给想搭建个人博客的小伙伴做个参考：

1. 准备源码文件​

整理好本地所有博客文件，包括 HTML 页面、CSS 样式文件、JS 交互文件、图片资源等，确保本地打开页面可以正常展示、交互无异常，页面布局、样式、功能全部调试完毕。

2. 创建专属仓库​

登录 GitHub 账号，新建公开仓库，仓库名严格按照规则填写：用户名.github.io（这是 GitHub Pages 专属域名格式，必须精准填写，否则无法正常访问），勾选初始化 README 文件，完成仓库创建。

3. 上传博客源码​

将本地整理好的所有博客静态文件，直接上传到该仓库根目录，也可以通过 Git 命令提交推送代码，确保首页文件 index.html 在仓库根路径下，保证站点可以正常识别入口文件。

4. 开启 GitHub Pages 服务​

进入仓库 Settings 页面，找到 Pages 配置项，在构建部署选项中，选择部署来源为 main 分支、根目录（root），保存配置。

保存后 GitHub 会自动执行构建部署，首次部署通常需要几十秒到两分钟左右，等待系统完成编译发布即可。

5. 访问上线博客​

部署完成后，通过专属域名 用户名.github.io 即可成功访问个人博客，一个完全属于自己的线上站点就正式诞生了。

部署过程踩坑小结​

看似简单的部署流程，实际操作中也遇到了几个小问题，在这里记录避雷：

• 仓库名格式错误：初期随意命名仓库，导致页面无法访问，必须严格遵循用户名.github.io 格式，且仓库必须设置为公开权限。
• 资源路径报错：本地正常、线上样式错乱，排查后发现是相对路径书写不规范，静态资源路径错误导致 CSS、JS、图片加载失败，统一修正相对路径后恢复正常。
• 部署延迟问题：代码推送后页面没有及时更新，GitHub Pages 部署存在短暂缓存延迟，耐心等待几分钟或强制刷新页面、清除缓存即可解决。

写在最后​

从零基础手写页面样式、调试交互 bug，到一步步配置、部署、上线，整个过程虽然繁琐，但成就感满满。

相比于套用模板的博客，自己手写搭建的站点，每一处细节都是心血，也更有温度。往后这里就是我的专属技术小天地，会持续更新技术笔记、学习心得、踩坑记录，慢慢打磨页面样式、优化交互体验，不断丰富博客内容。

如果你也想拥有免费的个人博客，不妨试试 HTML+CSS+JS + GitHub Pages 的组合，低成本、高收获，亲手搭建属于自己的线上自留地✨。