从零搭建 Astro 个人博客：一份适合新手的实践路线

想拥有一个自己的博客时，最难的往往不是写代码，而是不知道先做什么、文件该放哪里、改完以后怎么确认它真的生效。本文以这个 Astro 博客为例，把一次建站过程拆成几个可以逐步完成的小任务。它目前是本地网站，文中的上线部分是一份待办清单，不代表已经部署成功。

先想清楚第一版要有什么

第一版不必把评论、会员和复杂动画都做出来。对一个以文章为主的个人网站，我会先确认四件事：读者能看到首页介绍，能按主题找到文章，能打开文章详情页，也能在站内搜索关键词。等这些基本路径都通了，再考虑额外功能。

Astro 适合这个目标：文章可以写成 Markdown 文件，构建时生成静态页面。网站的文字、分类和页面样式也可以分别管理，不必为了发布一篇文章去改首页代码。不过，静态博客通常要在本地编辑文件；如果你希望像公众号一样在后台直接写稿，还需要额外接入内容管理工具。

第一步：确认电脑和项目能运行

进入项目文件夹后，先检查 Node.js 和 npm，再安装项目依赖：

node --version
npm --version
npm install

这个项目在 package.json 中要求 Node.js 22.23.4 或更高版本。接着按项目约定，在后台启动开发服务器：

npx astro dev --background
npx astro dev status

浏览器打开 http://localhost:4321/，能看到首页就说明本地服务已启动。需要停下时运行 npx astro dev stop。如果终端出现错误，先看第一条具体报错，再检查 Node.js 版本、依赖是否安装完成，以及是否在正确的项目目录。

第二步：认识几个最常改的文件夹

不需要一开始读懂整个项目。先记住下面这些位置：

位置	在这个博客里负责什么
`src/pages/`	首页、关于页、知识库、分类页和文章页的页面代码
`src/layouts/Layout.astro`	各页面共用的导航、页脚和页面外框
`src/content/blog/`	一篇文章对应一个 `.md` 文件
`src/content.config.ts`	检查文章标题、日期、分类等信息是否符合规则
`src/config/site.ts`	站名、介绍和五个分类的名称
`public/images/`	可以用网址路径引用的图片

例如，src/pages/articles/index.astro 对应知识库列表；src/pages/categories/[category].astro 是五个分类共用的模板。方括号里的 category 会由网址决定，因此不需要为「建站」和「SEO 内容」各复制一份页面。文章详情页同样由 src/pages/articles/[...slug].astro 统一生成。

第三步：写一篇真正属于自己的文章

在 src/content/blog/ 中新建一个英文文件名，例如 my-first-website-note.md。文件顶部的两行 --- 之间是文章信息，下面才是正文：

---
title: "我第一次搭建个人网站遇到的问题"
description: "记录从打开项目到找到解决办法的过程。"
pubDate: 2026-11-12
category: "website-building"
tags: ["建站", "实践"]
draft: false
---

先写清楚这篇文章要解决什么问题。

## 我遇到了什么

描述当时的现象和你已经尝试过的方法。

## 我怎样排查

按顺序记录操作、看到的结果和最终有效的步骤。

## 下次我会怎么做

总结一条可以复用的经验。

这里的 category: "website-building" 会把文章放进「建站」分类；draft: false 会让它出现在公开列表。想先保存草稿，就写 draft: true。文章的网址取自文件名，例如上面的文件会对应 /articles/my-first-website-note/。保存后，刷新本地分类页即可查看。

写教程时，尽量区分「我亲自验证过」与「准备尝试」。一篇短但步骤准确的记录，比堆很多未经验证的建议更有帮助。

第四步：检查列表、搜索和手机页面

文章保存后，依次检查：首页的最近更新、/articles/ 知识库列表、/categories/website-building/ 建站分类，以及文章详情页。确认标题、摘要、日期、正文链接都能正常显示。

这个博客使用 Pagefind 建立站内搜索索引。新文章要进入搜索结果，需要重新构建：

npm run build

构建会先生成静态页面，再为公开文章建立搜索索引。完成后刷新知识库页面，用标题里的一个独特词语试搜。若文章能打开却搜不到，先看 draft 是否为 false，再确认是否运行了完整的 npm run build。最后用手机宽度看一遍页面，检查标题、图片和代码块有没有横向溢出。

第五步：上线前完成这些检查

本地能打开不等于网站已经上线。准备连接 GitHub 和托管平台时，至少检查以下几项：

检查 astro.config.mjs 和 src/config/site.ts 的站点地址是否与实际部署域名一致。本站目前使用 https://www.allaido.com；RSS 和站点地图会使用这个地址生成链接。
将示例文章、示例图片和「关于我」中的文字换成自己的内容，再确认哪些文章需要设为草稿。
在部署平台使用本项目的完整构建命令 npm run build，输出目录为 dist；只运行 astro build 不会完成本项目的 Pagefind 搜索索引步骤。
部署后逐个打开首页、分类页、文章页和搜索，确认线上行为与本地一致。

RSS 是可选的订阅功能。直接在浏览器打开 /rss.xml 看到 XML 文字是正常的；如果暂时没有订阅读者，可以先把精力放在文章和基本导航上。

遇到问题时，按顺序缩小范围

如果网站突然不对，先判断问题发生在哪里：

**页面打不开：**检查开发服务器状态和终端报错。
**文章没有出现在分类：**检查文件是否位于 src/content/blog/，以及 category 是否写成 website-building。
**构建失败：**先检查文章顶部的 ---、日期格式和必填字段；src/content.config.ts 会校验这些信息。
**文章能看但搜不到：**确认 draft: false，然后重新运行 npm run build。
**本地正常、线上不正常：**查看托管平台的构建日志、域名配置和输出目录。

我的建议是：一次只解决一个最具体的问题，并把错误信息、修改过的文件和验证结果记下来。博客可以边写边完善；能持续发布真实、有用的记录，比第一天就做出一套复杂功能更重要。