從零搭建你的第一個 Astro 網站——實戰教學

準備工作

開始之前，你需要：

Node.js 18+（推薦 20 LTS）
一個套件管理器（pnpm 推薦，npm/yarn 也可）
一個文字編輯器（VS Code 有官方 Astro 擴充）

第一步：建立專案

pnpm create astro@latest my-astro-blog
cd my-astro-blog

引導過程會問你幾個問題：

安裝相依套件？ → Yes
初始化 Git？ → Yes
使用 TypeScript？ → Yes（嚴格模式）

第二步：專案結構

建立完成後，你會看到這樣的結構：

my-astro-blog/
├── src/
│   ├── pages/        # 你的頁面檔案 (.astro, .md, .mdx)
│   ├── components/   # 可複用組件
│   ├── layouts/      # 佈局組件
│   └── styles/       # 全域樣式
├── public/           # 靜態資源（圖片、字體、favicon）
├── astro.config.mjs  # Astro 配置
└── package.json

第三步：新增頁面

Astro 使用檔案系統路由——每個 .astro 檔案對應一個 URL 路徑：

---
// src/pages/index.astro — 你的首頁
---

<html>
  <head><title>我的部落格</title></head>
  <body>
    <h1>歡迎來到我的部落格</h1>
  </body>
</html>

新建 src/pages/about.astro 就會自動變成 /about。

第四步：加入部落格文章

安裝 Content Collections 支援：

mkdir -p src/content/posts

建立 src/content.config.ts：

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const posts = defineCollection({
  loader: glob({ pattern: "**/*.md", base: "./src/content/posts" }),
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    description: z.string(),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { posts };

然後在 src/content/posts/ 中建立你的第一篇文章：

---
title: '我的第一篇文章'
date: 2026-06-28
description: '這是我的第一篇部落格文章'
tags: ['生活', '入門']
---

## 開始寫作了

這是我使用 Astro 建立的第一個部落格。一切都很簡單、快速。

第五步：建立文章列表頁

編輯 src/pages/index.astro：

---
import { getCollection } from 'astro:content';

const posts = await getCollection('posts');
posts.sort((a, b) => b.data.date - a.data.date);
---

<html>
  <head><title>我的部落格</title></head>
  <body>
    <h1>最新文章</h1>
    <ul>
      {posts.map(post => (
        <li>
          <a href={`/posts/${post.id}/`}>
            <h2>{post.data.title}</h2>
            <time>{post.data.date.toLocaleDateString()}</time>
            <p>{post.data.description}</p>
          </a>
        </li>
      ))}
    </ul>
  </body>
</html>

第六步：動態路由顯示文章

建立 src/pages/posts/[...slug].astro：

---
import { getCollection } from 'astro:content';

export async function getStaticPaths() {
  const posts = await getCollection('posts');
  return posts.map(post => ({
    params: { slug: post.id },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<html>
  <head><title>{post.data.title}</title></head>
  <body>
    <article>
      <h1>{post.data.title}</h1>
      <time>{post.data.date.toLocaleDateString()}</time>
      <Content />
    </article>
  </body>
</html>

第七步：加入樣式

編輯 src/styles/global.css：

:root {
  --primary: #533afd;
  --ink: #1a1a2e;
  --canvas: #ffffff;
  --font-sans: 'Inter', system-ui, sans-serif;
}

body {
  font-family: var(--font-sans);
  color: var(--ink);
  background: var(--canvas);
  max-width: 720px;
  margin: 0 auto;
  padding: 2rem;
}

在 Layout 中引入這個 CSS。

第八步：建置與佈署

# 建置靜態網站
pnpm build

# 預覽結果
pnpm preview

輸出在 dist/ 目錄中，你可以把它部署到：

Cloudflare Pages — wrangler pages deploy dist/
Vercel — 連接 GitHub 倉庫即可
Netlify — 連接 GitHub 倉庫即可
GitHub Pages — 設定 Actions 自動部署

完整範例

以上就是一個完整的 Astro 部落格從零到部署的過程。不到 50 行程式碼（不計文章內容和樣式），你就擁有了：

一個自動生成的首頁文章列表
支援 Markdown 內容的文章頁面
類型安全的 metadata 驗證
可靜態部署的產出

這就是 Astro 的魅力——少寫程式碼，多做網站。