5个最好用的Astro博客主题推荐

第一步：安装主题#

最简单的方法是用包管理器。我推荐用pnpm，速度快而且省磁盘空间：

1
# 用pnpm（推荐）
2
pnpm create astro@latest --template satnaing/astro-paper
3

4
# 或者用npm
5
npm create astro@latest -- --template satnaing/astro-paper
6

7
# 或者用yarn
8
yarn create astro --template satnaing/astro-paper

运行命令后，它会问你项目名称。然后等它安装依赖，喝口水的功夫就装好了。

如果你用Docker，也可以这么搞：

1
docker build -t astropaper .
2
docker run -p 4321:80 astropaper

除非你的开发环境特别复杂，一般用不着Docker。

第二步：启动开发服务器#

装完之后进入项目目录，启动开发服务器：

1
# 先安装依赖（如果刚才没自动装的话）
2
pnpm install
3

4
# 启动开发服务器
5
pnpm run dev

然后打开浏览器访问 http://localhost:4321，就能看到你的博客了。

第三步：核心配置#

主要配置都在 src/config.ts 这个文件里：

1
export const SITE = {
2
  website: "https://你的域名.com", // 生产环境必填，开发时可以留空
3
  title: "你的博客名称",
4
  desc: "博客简介，用一两句话说清楚你的博客是关于什么的",
5
  author: "你的名字",
6
  // 其他配置...
7
}

开发阶段 website 可以先不填，等准备部署的时候再改成你的实际域名。这个很重要，因为它会用来生成网站地图和社交分享卡片的URL。

还有 astro.config.mjs 文件，这是Astro框架自己的配置。一般默认的就够用了，除非你要加插件或者改端口。

第四步：创建第一篇文章#

文章放在 src/content/posts/ 目录下。新建一个Markdown文件，比如 my-first-post.md：

1
---
2
title: "我的第一篇文章"
3
description: "简单介绍一下这篇文章讲什么"
4
pubDate: 2025-12-02
5
tags: ["Astro", "博客"]
6
---
7

8
# 正文开始
9

10
这里写你的文章内容，用Markdown格式就行。

保存文件，页面会自动刷新，你就能在首页看到这篇文章了。

注意几点：

• pubDate 是必填的，格式是 YYYY-MM-DD
• tags 是可选的，但建议填上，方便分类
• ogImage 可以指定社交分享时显示的封面图，不填的话会用默认图

修改主题颜色（可选）#

如果你想改主题颜色，可以参考官方的颜色自定义文档。AstroPaper支持多种配色方案，改起来也不复杂。

默认的颜色已经挺好看了，我自己也没怎么改。

安装相关#

yarn安装后报错找不到sharp模块

这是yarn 1的一个已知问题。手动装一下sharp：

1
yarn add sharp

装完重启开发服务器就好了。

Windows PowerShell运行诊断命令报错

如果你用的是Windows PowerShell，运行 astro check --watch & astro dev 可能会报错。这是因为PowerShell不支持 & 这种后台运行语法。

解决办法是装个concurrently包，或者干脆分开运行两个命令。

端口4321被占用

在 astro.config.mjs 里改个端口：

1
export default defineConfig({
2
  server: {
3
    port: 3000 // 改成你想要的端口
4
  }
5
})

配置相关#

改了配置不生效

配置文件改完后记得重启开发服务器，不然不会生效。我就是因为没重启，折腾了半小时才反应过来。

快捷键 Ctrl+C 停止服务器，然后重新 pnpm run dev。

图片显示不出来

图片要放在 public 文件夹里，引用的时候路径写成 /图片名.jpg。注意前面那个斜杠别漏了。

或者你也可以把图片放在 src/assets 里，然后在Markdown里用相对路径引用。两种方式都可以。

深色模式切换有bug

检查一下是不是自定义CSS的时候没考虑深色模式。主题色配置文件里应该有对应的深色模式变量，改颜色的时候记得两套都改。

部署相关#

部署到Vercel或Netlify失败

检查构建命令是不是 astro build，输出目录是不是 dist。这两个配错了肯定部署失败。

确认一下Node.js版本，Astro 4.0要求Node 18+，版本太低会报错。

部署后CSS样式丢失

这通常是base路径配置的问题。如果你的博客不是部署在根目录（比如 你的域名.com/blog/），需要在 astro.config.mjs 里设置base：

1
export default defineConfig({
2
  base: '/blog'
3
})

不然CSS和JS文件的路径会找不到。

添加评论系统#

推荐用Giscus（基于GitHub Discussions）或者Waline（轻量级独立评论系统）。集成起来不难，照着官方文档走就行。

Giscus的好处是完全免费，而且数据存在GitHub上不用担心丢失。Waline功能更丰富，但要自己部署服务器。

添加访问统计#

Google Analytics是最常用的，但如果你在意隐私，可以试试Plausible或者Umami，这两个都是注重隐私保护的统计工具。

集成方式就是在HTML模板里加一段统计代码，很简单。

优化图片加载#

如果你的文章里图片比较多，建议开启图片懒加载。Astro有内置的图片优化功能，用 <Image> 组件代替普通的 <img> 标签就能自动优化。

还可以考虑用CDN加速，把图片传到Cloudinary或者Cloudflare Images这种服务上，加载速度会更快。

多语言支持#

如果你的博客面向国际用户，可以加个多语言切换功能。Astro支持国际化，配置起来也不算麻烦。不过要注意，每篇文章都要翻译成多个语言版本，工作量会大不少。