附錄
常見問題
這裡收錄了非工程師最常問的問題：錯誤訊息怎麼讀、密碼為什麼不能寫在程式裡、Git 到底是什麼。看完這些，你跟 AI 的溝通效率會再上一個台階。
錯誤訊息怎麼讀：不要看到紅字就慌
很多非工程師看到一大片紅色的錯誤訊息就慌了。但其實，你只需要知道怎麼找三個關鍵資訊：
- 錯誤類型（通常在第一行或最後一行）
- 錯誤訊息（告訴你發生了什麼事）
- 出錯位置（在哪個檔案的第幾行）
來看一個實際的錯誤訊息：
Traceback (most recent call last):
File "/app/routes/user.py", line 42, in get_user
result = db.query("SELECT * FROM users WHERE id = " + user_id)
File "/app/database.py", line 15, in query
cursor.execute(sql)
TypeError: can only concatenate str (not "int") to str
File "/app/routes/user.py", line 42, in get_user
result = db.query("SELECT * FROM users WHERE id = " + user_id)
File "/app/database.py", line 15, in query
cursor.execute(sql)
TypeError: can only concatenate str (not "int") to str
拆解一下：
| 部分 | 在哪裡 | 告訴你什麼 |
|---|---|---|
| TypeError | 最後一行的開頭 | 錯誤類型：類型錯誤（數字和文字不能直接相加） |
| can only concatenate str... | 最後一行的說明 | 錯誤原因：你想把「字串」和「整數」接在一起 |
| user.py, line 42 | 中間的 Traceback | 出錯位置：user.py 檔案的第 42 行 |
| Traceback 中間部分 | 第 2-5 行 | Stack trace：從哪裡開始、經過哪裡、在哪裡爆掉 |
Stack Trace = 麵包屑
比喻：追蹤犯罪現場。
Stack trace 就像犯罪現場的監視器畫面。它告訴你：
「嫌犯從 A 房間出發 → 經過 B 走廊 → 在 C 房間犯案」
最上面是起點，最下面是出事的地方。通常你只需要看最下面幾行就夠了。
Stack trace 就像犯罪現場的監視器畫面。它告訴你：
「嫌犯從 A 房間出發 → 經過 B 走廊 → 在 C 房間犯案」
最上面是起點，最下面是出事的地方。通常你只需要看最下面幾行就夠了。
常見錯誤類型速查
| 錯誤類型 | 白話意思 | 常見原因 |
|---|---|---|
TypeError |
類型搞錯了 | 把數字當文字用、把空值當物件用 |
SyntaxError |
語法寫錯了 | 少了括號、多了逗號、拼錯字 |
ReferenceError |
找不到這個東西 | 變數名字打錯、忘了引入模組 |
404 Not Found |
頁面不存在 | 網址打錯、檔案被刪了、路由沒設定 |
500 Internal Server Error |
伺服器炸了 | 後端程式有 bug、資料庫連不上 |
403 Forbidden |
你沒有權限 | 沒登入、API key 過期、IP 被擋 |
CORS Error |
跨網域被擋 | 前端和後端網域不同，後端沒開放 |
ECONNREFUSED |
連線被拒絕 | 服務沒啟動、port 錯誤 |
最有效的求助方式
看到錯誤訊息？整段複製貼給 Claude。不要只說「它壞了」或「跑不動」。完整的錯誤訊息包含了 Claude 需要的所有線索：錯誤類型、出錯位置、呼叫堆疊。
你甚至不需要看懂它——直接複製貼上就是最好的溝通方式。
.env 環境變數：你的密碼本
為什麼密碼不能寫在程式碼裡？
想像這個場景：你寫了一個程式，裡面直接寫了你的資料庫密碼。然後你把程式碼上傳到 GitHub（一個公開的程式碼平台）。
恭喜，全世界都看到你的密碼了。
這不是開玩笑。每天都有人因為把密碼上傳到 GitHub 而被駭客入侵。GitHub 上有專門的爬蟲，24 小時在掃描新上傳的 API 金鑰。
比喻：把保險箱密碼寫在大門上。
你不會把家裡保險箱的密碼寫在大門上對吧？
把密碼寫在程式碼裡再上傳到 GitHub，就是在做這件事。
程式碼是公開的 = 大門是透明的 = 所有人都看得到你的密碼。
你不會把家裡保險箱的密碼寫在大門上對吧？
把密碼寫在程式碼裡再上傳到 GitHub，就是在做這件事。
程式碼是公開的 = 大門是透明的 = 所有人都看得到你的密碼。
.env 是什麼？
.env 就是「環境變數檔案」，白話說就是密碼本。它是一個純文字檔，裡面存放所有敏感資訊：
# .env 檔案的內容長這樣：
DATABASE_URL=postgresql://user:password123@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_abc123def456
LINE_CHANNEL_SECRET=your_channel_secret_here
OPENAI_API_KEY=sk-proj-xxxxxxxxxxx
DATABASE_URL=postgresql://user:password123@localhost:5432/mydb
STRIPE_SECRET_KEY=sk_live_abc123def456
LINE_CHANNEL_SECRET=your_channel_secret_here
OPENAI_API_KEY=sk-proj-xxxxxxxxxxx
重點來了：.env 這個檔案只放在你的電腦上，絕對不上傳到 GitHub。
怎麼確保不上傳？在 .gitignore（Git 的「忽略清單」）裡加上 .env，Git 就會自動忽略這個檔案。
.env.example 是什麼？
.env.example 是「密碼本的模板」。它告訴其他人「你需要填哪些密碼」，但不包含真實的值。
.env（真正的密碼本 — 不上傳）
DATABASE_URL=postgresql://admin:
realpassword@db.example.com
STRIPE_KEY=sk_live_real_key_123
API_SECRET=my_actual_secret
realpassword@db.example.com
STRIPE_KEY=sk_live_real_key_123
API_SECRET=my_actual_secret
.env.example（模板 — 可以上傳）
DATABASE_URL=your_database_url_here
STRIPE_KEY=your_stripe_key_here
API_SECRET=your_api_secret_here
# 只有欄位名稱，沒有真實值
STRIPE_KEY=your_stripe_key_here
API_SECRET=your_api_secret_here
# 只有欄位名稱，沒有真實值
必記原則
.env = 密碼本，只存在你的電腦上，絕不上傳。.env.example = 密碼本模板，告訴別人需要填什麼，可以上傳。
如果 Claude 幫你寫的程式碼裡出現了
sk_live_、password123 之類的真實密碼，馬上叫它改成環境變數。
Git 基礎：程式碼的「追蹤修訂」
如果你用過 Word 的「追蹤修訂」功能，你就已經理解 Git 的核心概念了。
Git = 程式碼的追蹤修訂功能。
想像你在寫一篇論文。每隔一段時間你就「另存新檔」：論文v1、論文v2、論文v3...。這樣如果改壞了，還可以回到之前的版本。
Git 做的就是這件事，但比「另存新檔」高級一百倍：
- 它記錄每一次修改了什麼（不是整份文件的副本）
- 它可以讓多人同時編輯同一個專案
- 它可以把修改上傳到雲端（GitHub）備份
想像你在寫一篇論文。每隔一段時間你就「另存新檔」：論文v1、論文v2、論文v3...。這樣如果改壞了，還可以回到之前的版本。
Git 做的就是這件事，但比「另存新檔」高級一百倍：
- 它記錄每一次修改了什麼（不是整份文件的副本）
- 它可以讓多人同時編輯同一個專案
- 它可以把修改上傳到雲端（GitHub）備份
核心概念對照表
| Git 術語 | 白話意思 | 生活比喻 |
|---|---|---|
| commit | 存一個紀錄點 | 遊戲的存檔點。隨時可以回到這裡 |
| push | 上傳到雲端 | 把存檔上傳到雲端備份（GitHub） |
| pull | 從雲端下載 | 把別人的最新存檔下載下來 |
| branch | 分支 / 平行宇宙 | 在分支上改東西，不影響主線。安全地實驗 |
| merge | 合併 | 把平行宇宙合併回主線。實驗成功了就併入 |
| clone | 複製整個專案 | 把別人的專案整份複製到你的電腦上 |
| staging | 準備區 | 把要存檔的東西先放到「待存清單」 |
最常用的 5 個 Git 指令
# 1. 查看現在的狀態（有什麼檔案被改了？）
git status
# 2. 把修改的檔案加到「待存清單」
git add . # 加全部
git add index.html # 只加指定檔案
# 3. 存檔（建立一個存檔點）
git commit -m "修好了登入頁面的 bug"
# 4. 上傳到 GitHub
git push
# 5. 下載別人的最新修改
git pull
git status
# 2. 把修改的檔案加到「待存清單」
git add . # 加全部
git add index.html # 只加指定檔案
# 3. 存檔（建立一個存檔點）
git commit -m "修好了登入頁面的 bug"
# 4. 上傳到 GitHub
git push
# 5. 下載別人的最新修改
git pull
Branch 的概念：平行宇宙
Branch 的運作方式
main（主線）： A ── B ── C ── D ── E（穩定版本）
\ /
feature/login： X ── Y ──（實驗新功能）
在 C 的時候，你開了一個新分支叫 feature/login
在分支上做了 X 和 Y 兩次修改
測試沒問題後，在 E 的位置合併回 main
如果實驗失敗？直接刪掉分支，main 完全不受影響
main（主線）： A ── B ── C ── D ── E（穩定版本）
\ /
feature/login： X ── Y ──（實驗新功能）
在 C 的時候，你開了一個新分支叫 feature/login
在分支上做了 X 和 Y 兩次修改
測試沒問題後，在 E 的位置合併回 main
如果實驗失敗？直接刪掉分支，main 完全不受影響
你不需要手動打這些指令
大部分時候，Claude Code 會幫你處理 Git 操作。但你需要知道這些概念，這樣當 Claude 說「我幫你建了一個 branch」或「要不要 commit 這些修改」時，你才知道它在說什麼。
常用套件速覽
「套件」（Package）就是別人寫好的工具，你可以直接拿來用，不需要自己從頭寫。就像蓋房子不需要自己燒磚——去建材行買就好。
i18n（國際化 / 多語言支持）
超重要：一開始就要規劃！
i18n 是 internationalization 的縮寫（i 和 n 之間有 18 個字母）。它讓你的網站支援多國語言。為什麼一開始就要規劃？因為如果你的網站寫了 200 頁之後才要加多語言，你得把 200 頁的文字一個一個抽出來。這是噩夢等級的工程。
一開始就規劃 i18n，就是把文字全部放在翻譯檔裡面（而不是寫死在程式碼裡）。之後要加新語言，只需要新增一個翻譯檔就好。
常見套件列表
| 套件 | 功能 | 白話說 |
|---|---|---|
| Tailwind CSS | 用 class 寫樣式 | 不用另外寫 CSS 檔，直接在 HTML 上寫 class 就有樣式。像是「預製傢俱」 |
| React | 前端 UI 框架 | 把網頁拆成一塊一塊的「元件」，重複使用。蓋積木式的網頁 |
| Next.js | React 的加強版 | React + 路由 + SSR + API，一個框架搞定全部 |
| Express | Node.js 後端框架 | 用 JavaScript 寫後端 API 最常用的工具 |
| Prisma | 資料庫工具（ORM） | 用 JavaScript 操作資料庫，不用寫 SQL。像是「資料庫翻譯機」 |
| Zod | 資料驗證 | 確保收到的資料格式正確。像是「品管員」 |
| next-intl / i18next | 多語言支持 | 讓你的網站支援中文、英文、日文等多國語言 |
| Stripe | 金流服務 | 讓你的網站能收信用卡。不用自己處理刷卡的複雜流程 |
| Resend / Nodemailer | 寄信服務 | 程式自動寄 email（驗證信、通知信、電子報） |
| Sharp | 圖片處理 | 壓縮、裁切、轉檔圖片。讓網站載入更快 |
你不需要記住這些套件
這張表是給你「認臉」用的。當 Claude 說「我用 Prisma 幫你寫 DB 查詢」或「要不要加 Zod 做 input validation」的時候，你至少知道它在說什麼。需要什麼套件？直接問 Claude：「我想做 XXX 功能，該用什麼套件？」