從零開始搭建 Astro 靜態網站與 CMS 後台完整教學

前言與架構概覽

這是一份針對初學者設計的完整建站指引。透過此方案，你可以實現：

完全免費託管：無需自備主機或伺服器，利用 Cloudflare Pages 提供的全球邊緣網絡與免費 pages.dev 網址。
Git 驅動發布：每次更新文章均由 GitHub 觸發自動構建，無需手動 FTP 上傳。
可視化 CMS 管理後台：透過 Sveltia CMS 在瀏覽器中直觀編輯、插入圖片與即時發布文章。

階段一：註冊基礎免費帳號

1. 註冊 GitHub 帳號

GitHub 用於存放網站所有源代碼與 Markdown 文章。

前往 github.com 點擊右上角 Sign up。
依序輸入你的電子郵件地址、設定強密碼，並自訂使用者名稱（Username，例如 larebirth）。
完成人機驗證並點擊 Create account。
前往電子信箱收取 8 位數驗證碼，輸入完成認證。

2. 註冊 Cloudflare 帳號

Cloudflare 負責靜態網頁託管、CDN 加速、免費 SSL 證書管理與全球分發。

前往 cloudflare.com 點擊右上角 Sign Up。
輸入電子信箱與密碼，點擊建立帳戶。
檢查信箱並點擊官方驗證連結以啟用完整功能。

階段二：在 GitHub 建立專案結構

此步驟直接在瀏覽器中使用 GitHub 網頁版編輯器完成，無需在電腦安裝 Node.js 或終端機。

步驟 1：建立全新倉庫（Repository）

登入 GitHub，點擊右上角 「+」 選取 New repository。
設定項目：
- Repository name：輸入 ai-never-late（或自訂專案英文名）。
- Visibility：選取 Public 或 Private 皆可。
- 勾選 Add a README file。
點擊下方綠色按鈕 Create repository。

步驟 2：啟動網頁編輯器

在倉庫頁面直接按下鍵盤上的 .（半角句號鍵），瀏覽器會自動載入網頁版 VS Code。

步驟 3：建立專案檔案清單

請在左側檔案樹建立以下檔案與目錄結構：

檔案路徑	作用說明
`package.json`	定義專案相依套件與 Astro 構建指令
`src/layouts/PostLayout.astro`	文章統一排版樣板
`src/pages/index.astro`	網站首頁與文章列表
`src/pages/posts/first-post.md`	第一篇測試文章
`public/admin/index.html`	Sveltia CMS 後台入口
`public/admin/config.yml`	後台欄位與 GitHub API 串接配置

1. 建立 `package.json`（專案根目錄）

{
  "name": "ai-never-late",
  "type": "module",
  "version": "0.0.1",
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
  "dependencies": {
    "astro": "^4.15.0"
  }
}

2. 建立排版模板 `src/layouts/PostLayout.astro`

先建立 src 資料夾，再建 layouts 資料夾，然後新建 PostLayout.astro：

---
const { frontmatter } = Astro.props;
---
<html lang="zh-HK">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{frontmatter.title}</title>
    <style>
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        max-width: 820px;
        margin: 40px auto;
        padding: 0 20px;
        line-height: 1.75;
        color: #24292e;
      }
      a { color: #0366d6; text-decoration: none; }
      a:hover { text-decoration: underline; }
      pre { background: #f6f8fa; padding: 16px; border-radius: 6px; overflow-x: auto; }
      hr { border: 0; border-top: 1px solid #e1e4e8; margin: 24px 0; }
    </style>
  </head>
  <body>
    <a href="/">← 返回首頁</a>
    <h1>{frontmatter.title}</h1>
    <p style="color: #586069;">發布日期：{frontmatter.pubDate}</p>
    <hr/>
    <article>
      <slot />
    </article>
  </body>
</html>

3. 建立網站首頁 `src/pages/index.astro`

在 src 下建立 pages 資料夾，然後新建 index.astro：

---
const posts = await Astro.glob('./posts/*.md');
---
<html lang="zh-HK">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>AI 研究筆記與個人里程碑</title>
    <style>
      body {
        font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
        max-width: 820px;
        margin: 40px auto;
        padding: 0 20px;
        line-height: 1.6;
        color: #24292e;
      }
      h1 { border-bottom: 2px solid #eaecef; padding-bottom: 12px; }
      .post-card {
        border: 1px solid #e1e4e8;
        border-radius: 8px;
        padding: 18px;
        margin-bottom: 18px;
      }
      .post-card a { text-decoration: none; color: #0366d6; font-size: 1.25rem; font-weight: bold; }
      .post-card p { margin: 8px 0; color: #586069; }
      .admin-btn {
        display: inline-block;
        background: #24292e;
        color: #ffffff;
        padding: 9px 16px;
        border-radius: 6px;
        text-decoration: none;
        margin-bottom: 24px;
      }
    </style>
  </head>
  <body>
    <a href="/admin/" class="admin-btn">進入 CMS 管理後台</a>
    <h1>AI 研究筆記與個人里程碑</h1>
    <div>
      {posts.map(post => (
        <div class="post-card">
          <a href={post.url}>{post.frontmatter.title}</a>
          <p>{post.frontmatter.description}</p>
          <small>{post.frontmatter.pubDate} · 標籤: {post.frontmatter.tags?.join(', ')}</small>
        </div>
      ))}
    </div>
  </body>
</html>

4. 建立第一篇範例筆記 `src/pages/posts/first-post.md`

在 pages 下建立 posts 資料夾，然後新建 first-post.md：

Markdown

---
layout: ../../layouts/PostLayout.astro
title: "我的第一篇 AI 研究筆記"
pubDate: "2026-09-28"
description: "測試 Cloudflare Pages 與 Astro 自動連動發布。"
tags: ["Astro", "Cloudflare"]
---

# 歡迎造訪

本網站由 Astro 靜態引擎驅動，並透過 Sveltia CMS 實現免代碼內容管理。

步驟四：加入 Sveltia CMS 視覺化管理後台

在專案根目錄建立 public 資料夾，再於內部建立 admin 資料夾，放入以下兩個檔案：

1. 後台入口 `public/admin/index.html`

HTML

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>內容管理後台</title>
    <script src="[https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js](https://unpkg.com/@sveltia/cms/dist/sveltia-cms.js)" type="module"></script>
  </head>
  <body></body>
</html>

2. 後台設定檔 `public/admin/config.yml`

(注意：repo 欄位請填入你的 GitHub帳號/倉庫名稱)

backend:
  name: github
  repo: larebirth/ai-never-late
  branch: main

media_folder: "public/images"
public_folder: "/images"

slug:
  encoding: "ascii"
  clean_accents: true
  sanitize_replacement: "-"

collections:
  - name: "posts"
    label: "AI 研究文章"
    folder: "src/pages/posts"
    create: true
    slug: "{{year}}-{{month}}-{{day}}-{{slug}}"
    fields:
      - { label: "排版模板", name: "layout", widget: "hidden", default: "../../layouts/PostLayout.astro" }
      - { label: "文章標題", name: "title", widget: "string" }
      - { label: "發布日期", name: "pubDate", widget: "datetime", date_format: "YYYY-MM-DD", time_format: false }
      - { label: "文章簡介 (SEO)", name: "description", widget: "string" }
      - { label: "標籤 (Tags)", name: "tags", widget: "list" }
      - { label: "正文內容 (Markdown)", name: "body", widget: "markdown" }

3. 提交代碼至 GitHub（Commit & Push）

點擊編輯器左側的 原始檔控制（Source Control） 圖示。
上方訊息欄輸入：init astro and sveltia cms。
點擊 提交與推送（Commit & Push） 按鈕。

步驟五：連接 Cloudflare Pages 自動構建

登入Cloudflare 控制台。
左側選單依序進入：Compute (Workers) > Workers & Pages。
點擊右上角 Create application $\rightarrow$ 切換到 Pages 分頁。
點擊 Connect to Git 並授權連接 GitHub 上的專案倉庫。
設定構建參數：
- Framework preset：選擇 Astro
- Build command：npm run build
- Build output directory：dist
點擊展開 Environment variables (advanced)，新增一筆環境變數：
- 變數名稱：NODE_VERSION
- 數值：20
點擊頁面最底部藍色按鈕 Save and Deploy。
等候約 1 分鐘，構建完成後即可取得專屬公開網址（例如 https://ai-never-late.pages.dev）。

步驟六：生成 GitHub Token 並登入 CMS 發文

Sveltia CMS 透過 GitHub API 直接存取與寫入倉庫檔案，需配置一組個人存取金鑰。

1. 生成 GitHub Token

在新分頁打開GitHub Personal Access Tokens 管理頁面。
點擊右上角 Generate new token $\rightarrow$ 選擇 Generate new token (classic)。
設定欄位：
- Note：輸入 sveltia-cms
- Expiration：選擇 No expiration（永久有效）
- Select scopes：勾選最頂部第一項 repo（包含其下所有細項權限）
滾動至底部點擊綠色 Generate token 按鈕。
複製頁面上生成的以 ghp_ 開頭之密鑰字串。

2. 登入後台發布第一篇正式文章

打開瀏覽器造訪後台入口：https://<你的專案名稱>.pages.dev/admin/。
點擊 Sign in with Personal Access Token，貼上剛才複製的 ghp_... 密鑰完成登入。
點擊右上角 New AI 研究文章：
- 填寫標題、日期、簡介與標籤。
- 正文內容直接貼上編寫好的 Markdown 內容。
點擊右上角 Publish（發布）。
系統會自動提交 Commit 至 GitHub，Cloudflare Pages 在 60 秒內重新編譯並將新文章自動發布上線。