如何用 Astro 搭建一个博客网站（入门版）
零基础也能跟着操作的 Astro 博客搭建指南，从环境准备、模板选择到部署上线
CONTENTS
👋 Hi，大家好，我是 Modusensus，一个对编程、设计与人文社科充满好奇的学习者。本文将带你一步步搭建一个属于自己的 Astro 博客网站，即使你是零基础也可以跟着操作。
一、为什么要选择 Astro
如果你只是想搭建一个个人博客网站，市面上有很多选择：可以买 WordPress 主题，也可以用 Hugo、Hexo，甚至可以直接用 Notion 分享页面。那我为什么会推荐 Astro？主要是因为它有几个很适合博客场景的特点。
第一，加载速度非常快。Astro 默认生成静态页面，在构建时直接输出 HTML 文件，不需要在用户访问时实时渲染。这意味着你写完文章部署后，读者打开页面时不需要等待后台处理，页面加载速度会更快。
第二，对博客内容支持很友好。你可以在 src/content/ 目录下直接写 Markdown 文件，不需要额外配置数据库，也不需要折腾复杂的 CMS 系统。对于只想专心写文章、不想花太多时间维护网站的人来说，这套流程会比较自然。
第三，可以逐步添加交互功能，而不是一次性全部加载。它的”岛屿架构”允许你只在需要的地方加载 JavaScript，比如只在某个页面加一个 3D 背景或粒子效果，其他页面保持纯静态。
第四，部署非常方便。Astro 生成的是纯静态文件，你可以直接推送到 GitHub 仓库，然后通过 GitHub Pages、Netlify 或 Vercel 部署上线，这些平台都支持从仓库自动构建和发布，不需要自己配置服务器。
第五，社区已经比较成熟。Astro 的官方主题库和社区模板已经积累了一定的数量，你不需要从零开始写布局，可以直接在现成的模板基础上修改。而且官方文档设计得比较清晰，是那种引导式学习风格，每个章节后面还有小练习，帮助你确认自己是否理解了当前内容。
二、环境准备
如果你还没有 GitHub 账号，需要先注册一个。后面我们会把博客代码推送到 GitHub 仓库，然后通过 GitHub Pages 部署上线。
注册地址：https://github.com
注册完成后，建议先在 VS Code 中登录 GitHub 账号（左侧活动栏找到”账户”图标，点击”使用 GitHub 登录”），方便后续推送代码。
常见的镜像源有：
选择一个即可。
三、去 Astro 官方主题库找到喜欢的模板
如果你只是想快速体验，可以直接使用 Astro 的模板命令来获取一个现成的博客框架。但如果你已经对项目结构有了一定的了解，也可以从空白项目开始，按需添加自己需要的功能和组件。那么后续只需要在 VS Code 的终端里输入运行 npm create astro@latest，一路选择同意即可。下面针对想用模板的开发者。
打开浏览器，进入 Astro 官方网站。
或者打开 astro.build/themes 这个地址，直接进入模板库，筛选你喜欢的模板。这里举个例子：
选择这个模板，点击在线演示可以预览模板效果，如果决定使用这个模板，可以直接点击开始使用，进入这个模板的 GitHub 仓库。
四、将模板运行到本地
新建一个空白的文件夹，再打开 VS Code，点击左上角的文件，选择打开文件夹，找到你刚才创建的那个文件夹打开。然后再打开 VS Code 终端。
在 VS Code 中，按下 Ctrl + ` 即可在底部打开终端窗口。（` 键位于键盘左上角，Esc 键的下方。）
你也可以通过顶部菜单 终端 → 新建终端 来打开。
补充说明： 如果你用的是 Mac，快捷键是
Cmd + `。Windows 和 Linux 系统则是Ctrl + `。
方式一：克隆仓库（推荐）
复制 GitHub 仓库的地址，在终端中执行：
git clone <仓库地址>
这种方式会保留完整的 Git 历史，方便后续拉取更新。
方式二：用 npm 拉取模板
如果你不想手动克隆，也可以直接用 Astro 的命令拉取模板：
npm create astro@latest -- --template 用户名/仓库名
例如：
npm create astro@latest -- --template uxiaohan/vhAstro-Theme
这种方式不需要手动 git clone，会自动下载模板并初始化项目。
比如这里针对我们使用的模板，可以输入：
npm create astro@latest -- --template AK0r/patrika
或者
git clone https://github.com/AK0r/patrika.git
还有一个办法是，在 VS Code 中用命令面板打开。
命令面板的操作流程
- 按
Ctrl+Shift+P打开命令面板 - 输入
gitcl或Git: Clone - 选择 “Clone from GitHub”
- 首次使用会提示登录 GitHub 账号
- 粘贴仓库的 URL，即 GitHub 仓库地址，输入你刚才挑选中的模板 GitHub 地址即可。
- 选择本地（也就是你当前打开的这个文件夹）的存放路径，确认即可开始克隆
可能遇到的问题
📦 情况一：npm install 下载太慢
如果在运行 npm install 时卡住，本质是 npm 官方源在国内访问慢。可以把镜像源配置写在”环境准备”这一步里，让读者提前设置好，后面就不用再操心了。
方法一：永久切换镜像源（推荐）
在终端执行这条命令，以后所有项目都会使用淘宝镜像（或者其他镜像，更换镜像源即可），一劳永逸：
npm config set registry https://registry.npmmirror.com
方法二：仅本次安装使用镜像（临时）
如果不想修改全局设置，可以在安装时加上 --registry 参数，只对当前命令生效：
npm install --registry=https://registry.npmmirror.com
💡 淘宝 npm 镜像的官方最新地址是
https://registry.npmmirror.com，旧地址registry.npm.taobao.org已经停用。
🔗 情况二：git clone 拉取仓库太慢
如果卡在 git clone 这一步，就需要加速 GitHub 本身。常见的方法是在原始仓库地址前加上代理前缀。
代理加速示例：
# 原始链接
git clone https://github.com/用户名/仓库名.git
# 加速链接
git clone https://githubproxy.cc/https://github.com/用户名/仓库名.git
镜像源和加速方式都是可选的，如果下载慢可以试试。
五、安装依赖并启动预览
在下载或者拉取好仓库之后，在 VS Code 的终端中继续输入：
npm install
npm run dev
然后打开浏览器访问 http://localhost:4321（或者其他终端中给出的链接）。
图中，这个网站的地址是 http://localhost:4321，我们也可以直接按住 ctrl 键点击终端中的地址，在 VS Code 中直接访问。
六、修改内容，变成自己的博客
当你第一次在浏览器里看到模板的样子时，它显示的是模板作者自己的内容。
你不需要成为前端专家才能修改这个模板。大部分情况下，你只需要在几个固定位置替换文字和文件内容，就能让这个网站变成你自己的博客。
左侧栏是整个博客网站的项目文件，点击即可在 VS Code 中编辑内容。你可以在 src/content/ 中管理文章，在 astro.config.mjs 中调整站点信息，其余部分几乎不需要改动。可以把”修改模板”拆成这些步骤：
1. 修改网站的基本信息
打开项目根目录下的 astro.config.mjs 文件（有些模板可能是 src/config.ts 或 src/config.js），找到类似这样的字段：
site: 'https://你的域名.com',
title: '你的博客标题',
description: '你的博客描述',
author: '你的名字',
把这些内容改成你自己的就行。改完后保存，刷新浏览器，网站的标题和描述就会自动更新。
2. 删除示例文章，换成你自己的
模板通常会自带几篇示例文章，存放在 src/content/ 目录下（也可能是 src/pages/posts/ 或 src/posts/）。你找到这些文件夹后，把里面的 .md 或 .mdx 文件全部删除，然后按照相同的格式创建你自己的文章。
每篇文章的文件开头，需要包含一个 frontmatter 信息区：
---
title: '文章标题'
date: '2026-08-13'
description: '这篇文章的简短描述'
tags: ['标签1', '标签2']
---
这个区域的信息决定了文章标题、日期、标签等内容在页面上如何显示。
文章正文就直接写在 --- 下方，使用标准的 Markdown 语法。
3. 修改首页的介绍文字
打开 src/pages/index.astro 文件，找到主页标题和介绍文字的部分，通常是类似这样的结构：
<h1>欢迎来到我的博客</h1>
<p>这里是我的个人写作空间，记录学习和生活。</p>
把这几行文字替换成你自己的介绍。
4. 替换导航菜单的文字
如果模板有导航菜单，通常在 src/components/Header.astro、src/components/Nav.astro 或 src/layouts/BaseLayout.astro 这些文件中。找到类似这样的列表：
<a href="/">首页</a>
<a href="/about">关于</a>
<a href="/blog">文章</a>
你可以修改菜单的文字，也可以调整它们的顺序或增删菜单项。
5. 更换头像或 Logo
模板可能会在 public/ 目录下放一张示例头像或 Logo。你用自己制作的头像或 Logo 替换掉同名的图片文件即可。如果文件名不同，需要同步更新配置文件或组件中引用的图片路径。
👀 修改完怎么看效果？ 每修改一处，保存文件后，浏览器中的页面会自动刷新，你马上就能看到改动后的效果。不需要手动刷新浏览器。
七、推送到 GitHub 并部署
本地预览满意之后，就可以把网站发布到线上了。这里以 GitHub Pages 为例。
1. 在 VS Code 中连接 GitHub 账号
点击左侧活动栏底部的”账户”图标，选择”使用 GitHub 登录”，授权后即可完成绑定。
2. 将代码推送到 GitHub 仓库
在终端中依次执行：
git add .
git commit -m "first commit"
git push
如果是全新项目还没有远程仓库，可以先在 GitHub 上新建一个仓库，然后按页面提示执行关联命令。
3. 启用 GitHub Pages
进入仓库主页，点击顶部菜单 Settings → Pages，在 “Branch” 下选择你要部署的分支（通常是 main 或 gh-pages），点击 Save。
稍等片刻，GitHub 会自动完成构建，完成后你会在同一页面看到你的博客地址，格式通常是：
https://你的用户名.github.io/仓库名/
🚀 除了 GitHub Pages，你也可以将代码连接到 Netlify 或 Vercel，它们支持自动监听仓库变动并重新构建部署，操作更简单，访问速度也更快。
方式二：用 Netlify 部署
Netlify 官网：https://www.netlify.com
- 注册并登录 Netlify，点击 Add new site → Import an existing project
- 选择 GitHub，授权后找到你的博客仓库，点击选择
- 构建设置一般会自动识别 Astro 项目，确认以下配置：
- Build command：
npm run build - Publish directory：
dist
- Build command：
- 点击 Deploy site，稍等片刻即可完成
部署成功后，Netlify 会分配一个随机子域名，格式类似：
https://随机名称.netlify.app
之后每次你将代码 push 到 GitHub，Netlify 会自动重新构建并发布，无需手动操作。
方式三：用 Vercel 部署
Vercel 官网：https://vercel.com
- 注册并登录 Vercel，点击 Add New → Project
- 选择 Import Git Repository，授权 GitHub 后找到你的博客仓库
- Vercel 会自动识别 Astro 框架，构建配置无需修改，直接点击 Deploy
- 等待构建完成，你的博客就上线了
部署成功后，Vercel 会分配一个子域名，格式类似：
https://仓库名.vercel.app
同样地，之后每次推送代码，Vercel 都会自动触发重新部署。
💡 三种方式怎么选？
- GitHub Pages：完全免费，适合不在意加载速度的情况，国内访问较慢
- Netlify：免费额度充足，构建速度快，操作直观，推荐新手使用
- Vercel：对前端框架支持最好，速度快，适合追求极致体验的用户
最后
如果目前你还是有些茫然，可以去阅读 Astro 官方教程——它不是那种堆砌术语的参考手册，而是一份引导式教程。你不需要一次性读完所有内容，只需要跟着步骤走，就能逐步理解核心概念。每个章节后面还有小练习，帮助你确认自己是否掌握了当前内容。
祝你搭建顺利，期待看到你的博客上线！🎉