本文記錄本站「修哥筆記」的建置全流程：技術選型、學院風設計、內容架構，以及最後佈署到 Ubuntu 主機並啟用 HTTPS 的實戰步驟。所有指令皆在真實環境跑通，並附上過程中踩到的坑。

目標讀者：想用現代靜態框架搭一個「以內容為主、可長期維護」的個人知識站，且主機是自己管理的 Ubuntu。

一、技術選型

• Astro v7：內容優先的靜態網站生成器，預設幾乎零 JavaScript，對閱讀型網站極快且對 SEO 友善。
• Tailwind 4：以 CSS-first（@theme）取代舊版 JS 設定檔，顏色與字體變數與樣式同層，維護直接。
• Node v24 LTS：Astro v7 所需的執行環境（本機以官方二進制安裝，不動系統舊版 Node）。
• Ubuntu + nginx + certbot：自管主機做靜態託管與免費 HTTPS。

二、準備 Node v24（不影響系統舊版）

官方二進制包解壓到家目錄即可，用 PATH 切換版本：

cd ~
curl -s -o node24.tar.xz https://nodejs.org/dist/v24.11.0/node-v24.11.0-linux-x64.tar.xz
mkdir -p ~/.local
tar -xf node24.tar.xz -C ~/.local
mv ~/.local/node-v24.11.0-linux-x64 ~/.local/node-v24
rm node24.tar.xz
~/.local/node-v24/bin/node -v   # 應顯示 v24.11.0

往後每次操作先帶入環境：

export PATH="$HOME/.local/node-v24/bin:$PATH"

三、初始化專案

mkdir -p ~/xiuge-notes && cd ~/xiuge-notes
npm init -y
npm install astro@^7.2.0 @tailwindcss/vite@^4.1.0 tailwindcss@^4.1.0

astro.config.mjs 整合 Tailwind 4（透過 Vite 插件，不再需要 tailwind.config.js）：

import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  site: 'https://wiki.nginx.tw',
  vite: { plugins: [tailwindcss()] },
});

src/styles/global.css 用 @theme 定義學院風設計變數：

@import "tailwindcss";
@theme {
  --color-navy: #1b2a41;     /* 海軍藍：標題/主色 */
  --color-cream: #f7f3e9;    /* 奶油白：背景 */
  --color-gold: #b08d57;     /* 金棕：裝飾線/強調 */
  --font-serif: "Source Serif 4", "Noto Serif TC", serif;
}

四、內容架構（Content Layer 實戰坑）

Astro v7 改用 Content Layer，與舊版 src/content/config.ts 寫法不同。設定檔位置須為 src/content.config.ts，且每個集合都要指定 loader：

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(),
    category: z.enum(['程式開發', '讀書筆記', '技術隨筆', '學習方法']),
    date: z.coerce.date(),
    excerpt: z.string(),
    tags: z.array(z.string()).default([]),
  }),
});

export const collections = { posts };

文章放在 src/content/posts/*.md，frontmatter 如上。兩個新手常踩的坑：

• 路由參數是 id 不是 slug：glob loader 下，getStaticPaths 要用 params: { slug: post.id }（過去是 post.slug）。
• 渲染要用 render() 而非 post.render()：在頁面中 import { render } from 'astro:content'，再 const { Content } = await render(post)。

src/pages/posts/[slug].astro 完整範例：

---
import { getCollection, render } from 'astro:content';
import PostLayout from '../../layouts/PostLayout.astro';

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 render(post);
---
<PostLayout post={post}><Content /></PostLayout>

五、學院風設計要點

• 配色：海軍藍做標題與主色（沉穩、權威），奶油白背景避免純白刺眼，金棕僅用於裝飾線與強調。
• 字體：中文 Noto Serif TC、西文 Source Serif 4，經 Google Fonts 載入，長文閱讀更順。
• 裝飾：雙線邊框（書本裝幀感）、章節間細線分隔符（❧ / ✦）、首字放大（drop cap）、書本感欄寬（正文 max-width 約 700px）。
• 互動：卡片式文章預覽，hover 時邊框轉金棕、輕微上浮、加柔陰影；分類導航 hover 底線滑入。

六、佈署到 Ubuntu（nginx + rsync）

靜態站產出在 dist/，佈署就是把這包複製到 nginx 的網站根目錄。本站用一條龍腳本 build-deploy.sh（需 root 執行），核心片段：

export PATH="/home/sugarwu/.local/node-v24/bin:$PATH"
cd /home/sugarwu/xiuge-notes
npm run build                       # 產出 dist/
rsync -a --delete dist/ /var/www/wiki.nginx.tw/html/
nginx -t && systemctl reload nginx

nginx 站台設定（/etc/nginx/sites-available/wiki.nginx.tw）重點：

server {
    listen 80; listen [::]:80;
    server_name wiki.nginx.tw;
    root /var/www/wiki.nginx.tw/html;
    index index.html;
    location / { try_files $uri $uri/ $uri.html /index.html =404; }
}

踩坑提醒：用 sudo bash script.sh 時，$HOME 會變成 /root，腳本內路徑務必寫絕對路徑，否則會找不到 dist/。

七、申請 HTTPS（Let’s Encrypt + certbot）

確認 nginx 已於 :80 正常服務後，安裝 certbot 並發證：

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d wiki.nginx.tw \
  --non-interactive --redirect --agree-tos \
  --email sugarwu@gmail.com --no-eff-email

certbot 會自動：

• 取得憑證
• 改寫 nginx 加上 listen 443 ssl 與憑證路徑
• 加入 return 301 https://$host$request_uri; 將 HTTP 轉向 HTTPS
• 啟用 certbot.timer 自動續期（憑證 90 天有效）

驗證：

curl -sI https://wiki.nginx.tw/        # 應為 HTTP/2 200
curl -sI http://wiki.nginx.tw/         # 應 301 轉向 https

八、日常維護流程

1. 在 src/content/posts/ 新增一份 .md（含 frontmatter）。
2. 一行上線：

sudo bash ~/xiuge-notes/build-deploy.sh

3. 開瀏覽器確認 https://wiki.nginx.tw/ 已更新。

小結

這套組合——Astro v7 寫作、Tailwind 4 設計、nginx 託管、certbot 加密——把「寫文章」與「維運」徹底分離：內容是 Markdown，基礎建設是一次性的腳本。未來無論換主機或加功能，都有清楚的界線可循。