INN666

繁體中文

English

繁體中文

English

外觀

使用 VitePress、GitHub 與 Cloudflare Pages 建立免費個人網站 ​

作者 HazimeEngineering
#VitePress #GitHub #Cloudflare

部落格文化已經存在好多年了，從第三方服務的無名小站、痞客邦，到比較自由的 WordPress，一直在推進。但是要完整擁有一個個人的部落格，其實一直都不容易。

使用第三方服務就受制於第三方的規範，而且無法防止平台置入廣告；不想使用第三方服務就要自架站台，但是自架的技術門檻相對高很多，像是租主機、買域名、自建專案等等。兩者對於想要認真長期經營個人品牌，卻沒有相關經驗，或是有相關技術但是生活忙碌的人來說，都十分勸退。

但是這個門檻近年也因為整個環境的發展開始逐漸降低。本文使用的技術組合 VitePress + GitHub + Cloudflare Pages，是一個十分輕量的個人部落格方案。不另外購買網域時，可以直接使用 Cloudflare Pages 提供的免費網址；想使用自己的網址，主要成本就是網域年費。

這套方案雖然無法搭建很大、很複雜的網站，但是對於想要入門當部落客的人來說，已經是個很好的選項。先寫一些文章起手，簡單、快速、維護成本低；未來想要擴大經營，也可以保留自己的域名轉移到其他服務，進可攻退可守。

這套方案適合誰？ ​

因為多少會接觸到程式碼和開發環境，所以比較適合有點工程師背景的人。不過程式碼和開發環境的部分都不算很深入，也很適合願意邊做邊學的新手。

它特別適合：

  • 想用 Markdown 管理文章。
  • 已經有在用 Git，或是正想開始學 Git。
  • 想架個人網站，但是不需要會員、購物車或複雜後台。
  • 希望維護成本低，又想保有內容和網域的控制權。

使用的服務 ​

VitePress ​

VitePress 是一個輕量的網站基本架構，可以快速搭建出一個能夠發布文章的網站平台。

它以 Markdown 管理頁面，最後輸出成靜態網站，而且免費。缺點是和 WordPress 比起來可用資源少很多，沒有一大堆現成的華麗版面和外掛可以直接用；如果想加比較複雜的互動功能，還是要自己開發。

GitHub ​

GitHub 是行之有年的版本控管服務。不過這次不只是拿來做版本控管，還會讓 Cloudflare Pages 透過 GitHub 自動發布更新。

GitHub 的使用者很多，就算最後不架部落格，其他專案也很可能會用到，學了有賺。

Cloudflare Pages ​

Cloudflare Pages 是這次使用的主機服務。比起租一台主機後自己架環境和做設定，Cloudflare 已經把很多服務包裝好了，靜態網站可以很快部署上去。

Cloudflare 本身也有 DNS 和網域服務，所以從買域名到架站都可以在同一個地方完成。不買域名的話，可以直接使用 Pages 提供的免費網址；未來想增加其他網站或 API 功能，也還有繼續擴充的空間。

整體發布流程 ​

  1. 建立 VitePress 專案。
  2. 使用 Git 管理專案，並推送到 GitHub。
  3. 在 Cloudflare Pages 匯入 GitHub repository。
  4. 設定建置指令與輸出目錄。
  5. 使用 Pages 提供的網址，或綁定自己的網域。
  6. 之後每次推送更新，Cloudflare Pages 都會自動重新部署。

安裝 Node.js ​

先安裝 Node.js，因為後續使用的 pnpm 指令依賴 Node.js。請到 Node.js 官方網站 下載目前受支援的 LTS 版本。

安裝完後，開啟命令提示字元（俗稱小黑窗）、PowerShell 或終端機，輸入指令確認版本：

bash
node -v
npm -v

兩個指令都有出現版本號就可以繼續。

安裝 pnpm ​

接著安裝 pnpm：

bash
npm install -g pnpm
pnpm -v

建立 VitePress 專案 ​

建立一個預計放部落格專案的資料夾，或是直接用指令建立：

bash
mkdir blog
cd blog

安裝 VitePress：

bash
pnpm add -D vitepress

如果出現 Build 失敗，而且終端機提示套件被 pnpm 的安全機制擋住，可以執行：

bash
pnpm approve-builds

依照畫面選擇 esbuild 即可。只核准自己確認需要的套件。接著初始化 VitePress：

bash
pnpm vitepress init

Theme 可以先選擇 VitePress 的預設主題，並選擇把 npm scripts 加入 package.json。完成後會產生 .vitepress/、index.md、package.json 等檔案。

在本機預覽 ​

執行：

bash
pnpm docs:dev

終端機會顯示本機網址，預設通常是：

text
http://localhost:5173

用瀏覽器開啟後，就可以看到 VitePress 的預設首頁。之後修改 Markdown，畫面也會自動更新。

正式部署前，也可以先跑一次正式建置確認沒有問題：

bash
pnpm docs:build
pnpm docs:preview

建立 Git 版本庫 ​

還沒安裝 Git 的話，先到 Git 官方網站 下載。關於 Git 本文不多做介紹，不懂的朋友可以另外搜尋 Git 教學，網路上已經有很多現成資源。

安裝完後，可以先設定 Git 的基本資料：

bash
git config --global user.name "Example"
git config --global user.email "example@example.com"

公開 repository 的提交紀錄可能會顯示這些資料。如果不想公開私人信箱，可以使用 GitHub 提供的 noreply 信箱。

把小黑窗的執行目錄移到剛剛建立的部落格專案底下，建立 Git 版控：

bash
git init -b main

接著在專案根目錄建立 .gitignore，避免 Git 把不需要的東西也放進版控：

text
node_modules/
.vitepress/cache/
.vitepress/dist/
dist/

正式把檔案加入版控：

bash
git add .
git commit -m "Initial VitePress project"

推送到 GitHub ​

前往 GitHub 建立一個空白 repository。建議先不要建立 README、license 和 .gitignore，後續初始化會比較單純。

把本機專案連到 GitHub，然後推送 main：

bash
git remote add origin https://github.com/example/example-blog.git
git push -u origin main

如果在設定 .gitignore 前就不小心提交了 node_modules，只補上忽略規則是不夠的，因為 Git 已經開始追蹤那些檔案。可以執行：

bash
git rm -r --cached node_modules
git commit -m "Remove node_modules from repository"
git push

這個指令只會停止追蹤 Git 裡面的 node_modules，不會把電腦上實際安裝的套件刪掉。

部署到 Cloudflare Pages ​

登入 Cloudflare 後，進入 Workers & Pages。要注意 Cloudflare 現在比較主推 Workers，建立 Pages 時不要直接點成 Worker。請在頁面中找到 Looking to deploy Pages? Get started；接著選擇 Import an existing Git repository，連接 GitHub 並選取剛才建立的 repository。

介面文字之後可能會改，不過大致流程就是連接 GitHub、選擇剛才建立的 repository，再填入建置設定。

這個專案把 VitePress 直接放在 repository 根目錄，所以設定如下：

text
Production branch: main
Build command: pnpm docs:build
Build output directory: .vitepress/dist
Root directory: /

如果你的 VitePress 專案放在 repository 的子目錄，Root directory 和輸出路徑就要跟著調整，不要完全照抄這裡的設定。

設定完成後開始第一次部署。成功的話，Cloudflare 會提供一個類似下面格式的公開網址：

text
https://example-blog.pages.dev

如果建置失敗，先看部署紀錄。常見原因包含 Node.js 或 pnpm 版本不符、建置指令打錯、輸出目錄不正確，或是不小心把 node_modules 提交到了 repository。

Pages 提供的 pages.dev 網址已經可以公開使用。如果只是測試或研究，做到這邊就可以了。

綁定自己的網域 ​

如果希望長期經營自己的品牌，可以考慮另外購買網域，再到 Pages 專案的 Custom domains 加入。自己的網域就像一個固定的網路地址，雖然要付年費，但是長期經營時很有幫助。

如果網域也是在 Cloudflare 購買和管理，可以從 Domains → Overview → Buy a Domain 搜尋想要的網域名稱，完成購買後再回到 Pages 綁定；DNS 通常可以在同一套流程裡完成。

常見網域的年費可能落在新台幣數百元到一千多元，但實際價格會依名稱、頂級網域與當時售價而不同，請以結帳頁面顯示的金額為準。不想增加成本的話，繼續使用 pages.dev 網址也完全沒問題。

日後如何發布文章？ ​

網站完成後，之後只需要寫 Markdown，確認本機建置正常，再推送：

bash
git add .
git commit -m "Publish a new article"
git push

Cloudflare Pages 就會自動完成建置和部署，不需要每次都自己手動上傳檔案。

後續發展與維護 ​

如果想一邊架站、一邊學習 coding，可以繼續研讀 VitePress 的文件和範例，再逐步做出自己想要的版面與功能。

如果不想把太多時間花在網站維護上，做到這裡也已經有完整骨架。後續可以請 AI Agent 協助調整版面、增加功能、整理文章與排查建置問題；這個部落格接下來也會由 Codex 協助開發和維護。不過每次修改後，仍建議先在本機預覽並執行正式建置，再把變更發布出去。

結語 ​

VitePress + GitHub + Cloudflare Pages 的組合幾乎沒有維護成本。它當然不適合拿來做很大、很複雜的網站，但是對想建立技術部落格的人來說，是個相當輕量又舒服的方案，也是這個部落格最後選擇的建置方式。