Astro 组件入门：看懂博客的页面结构

TL;DR

Astro 博客的每个页面由多个 .astro 组件组成。学会看懂组件代码，你就知道如何调整布局、加新功能、删不需要模块。

可以通过组件库使用指南了解本站已有的组件

.astro 文件是什么

.astro 是 Astro 框架的自有文件格式，混合了 HTML、CSS 和 JavaScript。看起来像这样：

---
// 顶部是"组件脚本"，用 JavaScript 写
const title = '我的博客';
const posts = await Astro.glob('./content/blog/*.md');
---

<!-- HTML 部分 -->
<html>
  <head><title>{title}</title></head>
  <body>
    <h1>{title}</h1>
    {posts.map(post => (
      <a href={post.url}>{post.frontmatter.title}</a>
    ))}
  </body>
</html>

<!-- 样式 -->
<style>
  h1 { color: var(--color-primary); }
</style>

三部分：

--- 之间：JavaScript 逻辑（数据获取、变量定义）
主体：HTML 模板（可以写 JSX 风格的表达式）
<style>：组件样式（可选）

组件层级结构

以云图札记文章页为例，结构大致如下：

MainLayout.astro（全局布局）
└── Header.astro（导航栏）
└── BlogPost.astro（文章主体）
    ├── ArticleHeader.astro（标题+元信息）
    ├── ArticleContent.astro（正文内容）
    └── ArticleFooter.astro（版权声明等）
└── Sidebar.astro（侧边栏）
└── Footer.astro（页脚）
└── BackToTop.astro（回到顶部）

打开 src/pages/blog/[...slug].astro 就能看到文章页入口。

常用操作

隐藏不需要模块

不想显示侧边栏？找到文章页组件，打开 <style> 找到侧边栏容器：

<style>
  .sidebar {
    display: none; /* 加这行隐藏 */
  }
</style>

用 display: none 隐藏而不是删除代码，方便以后恢复。

调整布局比例

侧边栏宽度太大？在 global.css 或组件样式里找宽度定义：

/* 原来 */
.sidebar { width: 280px; }

/* 改成 */
.sidebar { width: 240px; }
.content { flex: 1; }

在组件间传递数据

Astro 组件之间用 props 传递数据：

---
// Header.astro 接收 props
const { siteName = '默认名称' } = Astro.props;
---
<header>
  <a href="/">{siteName}</a>
</header>

在父组件里使用时：

<Header siteName="我的博客" />

动态内容与静态 HTML

Astro 支持两种渲染模式：

SSG（Static Generation）：构建时生成静态 HTML，速度快，适合内容固定页面
SSR（Server-Side Rendering）：每次访问实时生成，适合需要动态数据页面

云图札记用是 SSR 模式（output: 'server'），通过 @astrojs/cloudflare 适配器运行。

调试技巧

本地预览完整功能

npm run preview   # 而非 npm run dev

preview 模式使用构建后静态文件，能看到完整站点功能。dev 模式有些内容是动态模拟。

检查组件 props

在组件脚本里加 console.log：

---
const { title } = Astro.props;
console.log('Title prop:', title);
---

查看终端输出调试信息。

常见问题

改了组件没效果？

确认是在正确文件里改。src/pages/ 是路由页面，src/components/ 是可复用组件。

样式冲突了怎么办？

用开发者工具检查元素，看是哪个选择器样式在生效。.astro 文件的 <style> 是 scoped（作用域隔离）的，优先级可能不够。

想加一个新组件怎么做？

在 src/components/ 下新建 .astro 文件，在需要页面 import 它：

---
---
<MyNewComponent />

写在

看懂组件结构是定制博客第一步。不需要学很多前端知识，只要理解”HTML + CSS + 一点点 JS”就够了。

每次大改之前 git commit 一次，改坏了随时回退。放心折腾。

延伸阅读

种下你的想法

在花园里留下一条评论，和这篇文章一起生长。

COMMENTS