从零搭建个人博客：第一次上线

这个博客已经完成了第一次上线。页面还很简单，名字和自我介绍也没有确定，但从本地代码到线上首页的流程已经走通了。

这篇文章先记录当前做了什么、部署时遇到了什么，以及接下来怎样维护它。

第一版先做什么

第一版采用 Astro 和普通 Markdown：页面负责展示，文章保存在仓库里，用 Git 管理修改，再交给 Cloudflare Pages 构建和托管。

当前的结构是：

content/posts/           Markdown 文章
src/content.config.ts   文章元信息校验
src/lib/posts.ts         可见性、日期排序和文章地址
src/pages/index.astro   首页与文章列表
src/pages/posts/         文章详情页

首页使用黑白配色和衬线字体，不单独起博客名字。左上角放姓名，中间用一句话打招呼，下面直接展示文章。

文章详情页以阅读为主：正文居中，桌面端最大宽度约 720px，目录默认收起。宽屏时目录在左侧，手机上放到正文前方。页面也支持深浅色切换。

目前没有管理后台，也没有一键发布脚本。先手动操作，熟悉写文章、检查内容、提交代码和查看部署结果的完整流程。

文章就是一个 Markdown 文件

文章放在 content/posts/ 中。文件开头的元信息描述标题、简介、主分类、日期和状态，正文从二级标题开始。

例如，一篇草稿可以这样写：

---
title: "文章标题"
description: "用一句话介绍文章内容。"
category: "建站记录"
status: draft
created: "2026-10-30"
updated: "2026-10-30"
---

每篇文章只有一个主分类，不使用 Tag。标题、简介、分类不能为空，日期必须合法，元信息不符合要求时构建会报错。

draft 和 review 状态的普通文章不会出现在首页，也不会生成详情页。准备公开时，需要改为 published，并填写 published 日期。

这里要区分两件事：允许进入公开构建，不等于已经上线。文章是否成功发布，还要看部署是否成功，以及线上地址能否实际访问。

从本地预览到线上部署

本地启动开发服务：

npm run dev

提交前检查类型和构建结果：

npm run check
npm run build
npm run preview

开发预览和生产预览并不完全相同。仓库中有一篇用于检查排版的示例，它只出现在开发服务里，不会进入正式构建。因此，第一次上线后首页没有文章，是当前过滤规则下的预期结果。

部署采用 GitHub 与 Cloudflare Pages 的 Git 集成。Pages 的配置是：

配置项	本项目使用的值
生产分支	main
构建命令	npm run build
输出目录	dist
Node 版本	22.23.4

仓库推送到生产分支后，由 Pages 自动构建并部署。源码仓库是私有的，但部署出来的网站可以公开访问，这两种访问权限是分开的。

这次遇到的一个入口问题

部署时先进入了 Workers 的创建流程。配置页面出现了 npx wrangler deploy，而当前准备的是 Pages 所需的构建命令和输出目录，两边并不对应。

后来在创建应用页面底部找到“继续前往 Pages”，进入 Pages 流程后完成了部署。

这并不说明 Workers 不能部署静态博客，只是当前项目没有按那条部署路径准备配置。此前失败日志没有包含完整报错，因此不能把某个具体错误当作已经确认的根因。

对这次搭建来说，实际有用的判断是：先确认自己创建的是哪一种项目，再填写与该流程对应的配置。控制台入口可能调整，不必把这次的按钮位置当成永久不变的操作步骤。

已经完成与还没完成的部分

线上首页已经能够访问，姓名与简介暂时使用占位文字。文章列表、Markdown 详情页、目录和主题切换已在本地实现并检查过；首篇正式文章的线上阅读流程，还需要实际发布后再验证。

还有一个已知问题：访问不存在的示例文章路径，会返回首页和 HTTP 200，而不是独立的 404 页面。它不影响首页访问，但后续需要补上，让无效地址得到明确反馈。

接下来先完成这篇文章的校对与发布，再逐步补充个人介绍和内容。博客的基本结构已经有了，后续维护可以围绕真实使用中遇到的问题继续推进。