前言

上一篇我們認識了 Cloudflare Pages 是什麼，這篇要實際動手做：從零開始建立一個 React 專案，然後部署到 Cloudflare Pages。整個過程大約只需要 10-15 分鐘。

學習目標

讀完本篇後，你將能夠：

• 建立一個簡單的 React 專案（使用 Vite）
• 將專案推送到 GitHub
• 在 Cloudflare Pages 完成首次部署

前置準備

開始之前，請確認你已經：

• 安裝 Node.js（建議 18 版以上）
• 有 GitHub 帳號
• 有 Cloudflare 帳號（免費註冊即可）
• 了解基本 Git 操作（git add、git commit、git push）

第一步：建立 React 專案

我們使用 Vite 來建立 React 專案。Vite 是目前最流行的前端建構工具，速度快、設定簡單。

1.1 執行建立指令

打開終端機，執行：

npm create vite@latest my-react-app -- --template react
Code language: CSS (css)

這行指令做了什麼？

• npm create vite@latest：使用最新版 Vite 建立專案
• my-react-app：專案資料夾名稱（可以改成你喜歡的名字）
• -- --template react：使用 React 模板

執行後會看到類似這樣的輸出：

Scaffolding project in /path/to/my-react-app...

Done. Now run:

  cd my-react-app
  npm install
  npm run dev

1.2 安裝相依套件

cd my-react-app
npm install

1.3 本地測試

npm run dev

打開瀏覽器，前往 http://localhost:5173，你會看到 Vite + React 的歡迎頁面。

按 Ctrl + C 停止開發伺服器。

第二步：測試 Build

部署前，我們要確認專案可以正常打包。

npm run build

成功的話，會看到類似：

vite v5.x.x building for production...
✓ 34 modules transformed.
dist/index.html                   0.46 kB │ gzip:  0.30 kB
dist/assets/react-xxxxx.svg       4.13 kB │ gzip:  2.05 kB
dist/assets/index-xxxxx.css       1.39 kB │ gzip:  0.72 kB
dist/assets/index-xxxxx.js      143.36 kB │ gzip: 46.07 kB
✓ built in 1.23s

重點觀察：

• 打包輸出在 dist 資料夾
• 這個資料夾名稱等一下設定 Cloudflare Pages 時會用到

你可以用以下指令在本地預覽打包結果：

npm run preview

第三步：推送到 GitHub

3.1 建立 GitHub Repository

1. 前往 github.com
2. 點擊右上角的 + > New repository
3. Repository name 填入 my-react-app
4. 選擇 Public 或 Private 都可以
5. 不要勾選 “Add a README file”（因為 Vite 已經建立了）
6. 點擊 Create repository

3.2 推送程式碼

Vite 已經幫我們初始化 Git，所以直接推送即可：

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/你的帳號/my-react-app.git
git push -u origin main
Code language: JavaScript (javascript)

第四步：在 Cloudflare Pages 部署

4.1 進入 Cloudflare Pages

1. 前往 dash.cloudflare.com
2. 左側選單點擊 Workers & Pages
3. 點擊 Create application
4. 選擇 Pages 標籤
5. 點擊 Connect to Git

4.2 連接 GitHub

1. 選擇 GitHub
2. 第一次使用需要授權，點擊 Install & Authorize
3. 選擇要授權的 Repository（可以選擇只授權特定 repo）
4. 完成授權後，選擇剛才建立的 my-react-app
5. 點擊 Begin setup

4.3 設定 Build 參數

這是最重要的一步，設定值如下：

選擇 Vite 作為 Framework preset 後，Build command 和 Build output directory 會自動填入正確的值。

如果你用的是其他框架，這兩個值會不同：

4.4 開始部署

點擊 Save and Deploy，然後等待部署完成。

部署過程中，你會看到即時的 log 輸出：

Cloning repository...
Installing dependencies...
npm run build
...
Build completed successfully!
Deploying...
Success! Your site is live!

整個過程通常在 1-2 分鐘內完成。

第五步：查看部署結果

5.1 預覽網址

部署完成後，Cloudflare Pages 會給你一個預覽網址，格式是：

https://my-react-app.pages.dev
Code language: JavaScript (javascript)

或者是帶有 commit hash 的版本：

https://abc1234.my-react-app.pages.dev
Code language: JavaScript (javascript)

點擊連結，你會看到跟本地一樣的 React 歡迎頁面，但這次是在全球 CDN 上運行！

5.2 部署資訊

在 Cloudflare Pages 的專案頁面，你可以看到：

• Production URL：正式環境的網址
• Last deployment：最後一次部署時間
• Status：部署狀態（Success / Failed）

自動部署：推送即部署

最棒的是，現在每次你推送程式碼到 GitHub，Cloudflare Pages 都會自動部署。

試試看：

1. 修改 src/App.jsx 中的文字
2. 推送到 GitHub：

git add .
git commit -m "Update welcome message"
git push
Code language: JavaScript (javascript)

1. 回到 Cloudflare Pages，你會看到新的部署正在進行
2. 部署完成後，重新整理網頁就能看到更新

常見問題排解

Build 失敗：找不到 dist 資料夾

確認 Build output directory 設定為 dist（Vite）或 build（Create React App）。

Build 失敗：npm install 錯誤

檢查 package.json 是否正確推送到 GitHub。

部署成功但頁面空白

1. 檢查瀏覽器的開發者工具（F12）有無錯誤
2. 確認 vite.config.js 中的 base 設定（如果有設的話）

部署成功但顯示 404

確認 Build output directory 設定正確。可以在 Cloudflare Pages 的部署詳情中查看實際輸出的檔案。

本篇重點整理

1. 建立專案：npm create vite@latest my-react-app -- --template react
2. 測試 Build：npm run build，確認 dist 資料夾有產生
3. 推送 GitHub：建立 repo 並推送程式碼
4. Cloudflare Pages 設定：
   • Framework preset：Vite
   • Build command：npm run build
   • Build output directory：dist
5. 自動部署：推送到 GitHub 就會自動觸發部署

下一篇預告

目前我們的網站網址是 xxx.pages.dev，下一篇會教你如何綁定自訂網域，讓網站使用你自己的網址。