用 Astro 搭建一个自己的博客：从第一篇文章到上线

Astro 很适合做内容型博客：默认在构建时把页面渲染成静态 HTML，浏览器拿到的是完整内容，上线后不需要常驻的服务器进程。下面从零开始，创建项目、写第一篇文章、加一个能点进文章的首页，最后把它部署到线上。

一、准备环境

需要 Node.js 22.12 及以上（用官方的偶数 LTS 版本最稳妥）、npm，以及一个顺手的编辑器。先确认版本：

node -v
npm -v

如果命令找不到，先安装 Node 并确保它已加入 PATH。

二、创建项目

用官方脚手架创建项目：

npm create astro@latest

脚手架会依次询问：项目目录填 ./my-blog；模板选择最精简的 minimal（空白起步）即可；提示是否安装依赖时选“是”。完成后进入目录并启动开发服务器：

cd my-blog
npm run dev

终端会打印一个本地地址，默认是 http://localhost:4321/；浏览器打开就能看到初始页面。改动文件会热更新，按 Ctrl + C 结束。

如果创建时选择不安装依赖，之后在项目目录执行 npm install 即可。npm ci 适合已经有匹配锁文件的项目，不是初次安装的必要步骤。

三、认识几个常用目录

先认识几个常用目录；精简模板没有生成的目录，可以按需新建：

src/pages/：页面与路由，一个文件对应一个地址；
src/components/：可复用组件；
src/layouts/：页面外壳；
src/styles/：样式；
public/：原样复制到产物的静态资源。

一个文件就是一个地址：src/pages/about.astro 对应 /about/。public/ 与 src/ 的区别，是前者不做任何处理、原样复制。先把“写页面 → 写文章 → 构建”的闭环跑通就够了。布局复用、内容集合、样式体系都可以之后按需再加，不必一开始就搭得很全。

四、写第一篇文章

Astro 可以直接把 Markdown 当作页面。新建 src/pages/posts/hello.md，它对应的地址是 /posts/hello/：

---
title: 我的第一篇文章
date: 2026-10-07
---

## 你好，世界

这是用 Markdown 写下的第一篇内容。标题和日期是我自己加的字段，
它们不会自动出现在页面上，需要时可以在布局里读取和展示。

几个要点：

文件放在 src/pages/ 下，路径就是网址，posts/hello.md 会生成 /posts/hello/；
上面的 title、date 属于自定义元数据，默认不会自动渲染；想让它们显示，就要在模板里读取；
正文里的标题和段落会正常渲染成页面内容，所以页面本身是“自足”的。

最上面的 --- 包起来的是 frontmatter，用来放文章的元数据；它下面才是正文。普通 Markdown 页面也可以不写 frontmatter，需要保存标题、日期等信息时再添加。

五、让首页链接到文章

新建或替换 src/pages/index.astro，写一个最小的首页：

---
---
<html lang="zh-CN">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>我的博客</title>
  </head>
  <body>
    <h1>我的博客</h1>
    <p>这里会记录我学到的东西。</p>
    <a href="/posts/hello/">阅读第一篇文章</a>
  </body>
</html>

这样一个最小的博客就成型了：首页可用、文章可访问，也不需要任何隐藏的列表机制。等熟悉之后再考虑抽取布局、做文章列表或样式主题。

六、放一张自己的图片

示例图片

把图片放进 public/，并用根路径引用。例如文件 public/images/cover.jpg，在页面里就写成 /images/cover.jpg：

<img src="/images/cover.jpg" alt="封面" />

public/ 里的资源会原样复制到产物，引用路径从 / 开始。本地磁盘路径无法供线上读者访问；使用自己的图片时，要将文件一起部署。

七、构建与本地预览

开发服务器适合调试，真正上线的是构建产物：

npm run build

产物输出在 dist/。想在本地确认效果，运行：

npm run preview

终端同样会打印一个本地地址，按提示访问即可；不要直接双击 dist/index.html，因为页面资源使用根路径，必须经由服务器访问。Astro 默认输出静态站点，浏览器端不需要 Node 运行。

八、上线

静态站点有两种常见做法：

交给支持 Git 集成的静态托管平台：连接你的仓库，构建命令填 npm run build，输出目录填 dist，之后推送代码就能自动构建部署；
自己有一台已配置好的静态 Web 服务：把 dist/ 里的内容上传到站点根目录即可，不需要在服务器上跑 Node 构建。

绑定自定义域名与启用 HTTPS，按所用平台的提示完成域名解析。使用自有静态 Web 服务时，还需要确认文章路径和不存在的地址如何处理；仅上传文件不一定会自动配置自定义 404。

九、日常写作节奏

固定成一条简单流程：写 Markdown → npm run dev 预览 → npm run build 构建 → 用上面任一方式发布。源码用 Git 做版本管理与备份，不要只备份 dist/。

一般来说，只把源码纳入版本管理就够了，dist/ 由构建重新生成；需要离线核对时再单独保存一份即可。

十、常见问题

依赖没装上：在项目目录执行 npm install。
端口被占用或想换端口：按终端打印的地址访问，也可用 npm run dev -- --port 4322 指定端口。
图片或样式 404：检查资源是否一同构建和上传；public/ 中的文件用根路径引用，样式也可能来自 src/ 并由构建工具处理。
本地能看但线上没有：git push 只把代码推到远端，托管平台还需要再构建一次，去平台查看构建状态即可。
想加文章列表：之后可以用 Astro 的内容集合读取 Markdown，或在页面里遍历文件；初学时手动链接就够用。
构建失败怎么看：终端会指出报错的文件与位置，按提示修正后重新 npm run build。
能用现成主题吗：可以，等熟悉了最小结构，再引入布局与样式会更容易排查问题。
一定要最新 Node 吗：按 Astro 当前文档要求的版本即可，用偶数 LTS 更稳，遇到语法或构建报错时先核对版本。

十一、写在最后

从零到一个能上线的博客，核心其实只有三步：写页面、写内容、构建发布，剩下的是逐步打磨。

搭建过程中遇到的取舍和解决办法都值得记下来；也欢迎把经验与改进分享出来，让更多人少走一点弯路。