下載並拆解 ChatGPT App（Next.js 16）

1. 介紹

本講座的目標很簡單也很關鍵：把你從零帶到「我已在本機跑起一個可用的 ChatGPT App，我能在瀏覽器中看到頁面，而且一切正常」的狀態。

我們不會深入鑽研 Next.js 的程式碼，也不會設定 ChatGPT 的 Dev Mode，更不會先開通隧道——那些是本模組後續的講座。今天只聚焦三件事：

1. 準備環境：Node.js、npm、Git、編輯器與基本檢查，確保 Next.js 16 不會在你的 Node 版本上崩潰。
2. 下載可用的 ChatGPT App（基於 Next.js 16）：透過 git clone，或使用 GitHub 範本/CLI。
3. 安裝相依、設定含有 OPENAI_API_KEY 的 .env，並執行 npm run dev，確認你的 http://localhost:3000 一切正常。

若你在講座結束時能在瀏覽器看到範本的起始頁，且終端機中的 dev 伺服器沒有紅字錯誤——那就表示你已經擁有一個可運作的 ChatGPT App 了。

2. 開發者的最小環境

先從基礎設施開始。沒有它，再潮的 LLM 也幫不上忙——Next.js 根本跑不起來。

Node.js 與 npm

基於 Next.js 16 的現代 Apps SDK 樣板需要最新的 Node。建議使用 LTS 分支——目前例如是 Node 24 LTS。最低可接受版本為 20.9，自此開始 Next.js 16 才有官方支援。

在終端機檢查版本：

node -v
npm -v

如果你沒有看到整齊的 v24.x.x，而是像 v16.13.0 之類的版本，很可能範本無法安裝相依，或 Next.js 會抱怨不支援該 Node 版本。

升級可以用「最簡單」的方式——下載你作業系統對應的官方 Node.js 安裝程式——或者，如果你已經熟悉 Linux/macOS，也可以用 nvm/fnm。在本課程中我們不會深入版本管理工具，重點是先讓 LTS 版本可用。

Git

我們需要 Git 來取得範本，未來也要用它提交變更。檢查方式：

git --version

如果找不到該指令，就需要安裝 Git（Windows 安裝程式、macOS 的 Homebrew、或 Linux 的套件管理器）。對於執行 App 本身，Git 並非絕對必要，但在 2025 年還不用 Git，差不多就像寫 TypeScript 卻不知道什麼是介面一樣。

程式碼編輯器

預設推薦 WebStorm。JavaRush 提供了專用外掛，讓你能夠幾個點擊就完成解題。對前端與 Node 來說，它幾乎是事實上的標準。

當然也可以使用 VS Code，建議安裝以下基本延伸模組：

• TypeScript/JavaScript 支援；
• ESLint（範本通常已設定好 linter）。

等我們開始修改範本程式碼時，這會讓你輕鬆很多。

OpenAI／ChatGPT 帳號與 API 金鑰

本講座只需能在瀏覽器使用 ChatGPT（登入你的帳號）。Dev Mode 我們會之後再接，但現在先確認你能進入網頁介面，且看得到開發者相關分頁（依 OpenAI 當前政策，可能是 Plus/Team/Enterprise）。

未來會需要 OpenAI API 金鑰（OPENAI_API_KEY）。我們的第一個專案其實在沒有金鑰時也能起來：起始 UI 完全是靜態的。不過本講座仍會使用金鑰，並把它放到 .env 檔案裡——稍後會說明怎麼做以及為何較安全。

金鑰可於 OpenAI 管理頁取得，請把它當機密保存，不要進版本庫，對待它就像護照號碼——甚至更敏感。

3. 從哪裡取得可用的 ChatGPT App

現在進入最愉快的部分：拿一個已設定好的起始專案，它已經配置為 ChatGPT App。

為什麼是這個專案

這是一個非常簡單的 Next.js 16 專案，把兩個角色放在同一個版本庫中：UI 小工具與 MCP 伺服器。

結構已經備妥：

• 有一個 React 頁面，會以小工具的形式被渲染；
• 有一個 MCP 伺服器的 endpoint，ChatGPT 會連到這裡以使用工具；
• 有完整的 Next.js 設定（包含像 assetPrefix 這類細節，確保在 ChatGPT 的 iframe 中能正確載入資產）。

這比從零開始組裝要好太多了。

方式一：複製 Git 儲存庫

最直接的途徑：

git clone https://github.com/codegym-cc/chatgpt-apps-examples/helloworld my-chatgpt-app
cd my-chatgpt-app/01-chatgpt-app-helloworld

儲存庫名稱未來可能會有些差異，所以在複製指令前，建議先參考官方文件或本講座下方的最新連結。

git clone 會在你本機建立 my-chatgpt-app 資料夾，裡面包含整個範本內容，且已初始化好 Git 版本庫。

方式二：在 GitHub 上點「Use this template」

如果你想直接在 GitHub 內擁有自己的儲存庫，可以這樣做：

1. 打開 GitHub 上的範本頁面。
2. 點擊「Use this template」。
3. 基於該範本建立自己的儲存庫，例如 username/study-buddy-chatgpt-app。
4. 之後再把你自己的儲存庫複製到本機。

本質上結果一樣：你會在本機得到含有範本程式碼的資料夾，只是 Git 的遠端不是指向 CodeGym，而是指向你自己的儲存庫。

方式三：CLI 範本

未來很可能會有 OpenAI 的官方 CLI 工具，類似這樣：

npx create-openai-app@latest my-chatgpt-app

目前還沒有，因為 ChatGPT 應用才剛起步。但在你讀到這裡時，也許已經出現了。務必在 Apps SDK 的官方文件中搜尋是否已有這類指令。

邏輯相同：CLI 只是把相同或非常類似的範本下載並展開。先前在建立 ChatGPT 外掛時就有類似工具，因此過一陣子我認為應該也會有對應於應用的版本。

4. 安裝相依並初探專案

假設你已經有一個包含可用專案的 my-chatgpt-app 資料夾。是時候安裝相依套件了。

npm install

切換到專案資料夾並安裝相依：

cd my-chatgpt-app
npm install

指令會讀取 package.json，其中已列出必要套件：Next.js、React、Tailwind、Apps SDK 與 MCP SDK（@modelcontextprotocol/sdk）。

完成後會出現 node_modules 目錄——就是那個動輒好幾百 MB 的怪獸；我們絕不把它提交到 Git。它通常已在範本的 .gitignore 中，因此不需另外設定。

如果安裝相依過程中發生錯誤，別緊張：稍後會整理常見問題與處理方式。

快速瀏覽內容

現在不需要深入資料夾結構——那是下一講的主題，我們會詳細說明各檔案所在。不過先瞄一下專案根目錄有幾個重點：

• package.json——相依與 script 列表。
• next.config.ts——Next.js 設定，包含在 ChatGPT 內部運作的重要調校。
• tsconfig.json——TypeScript 設定。
• app/——主要的 UI 程式碼與 MCP 路由都在這裡。

下次我們會把這片「黑森林」變成清楚的地圖。

5. 設定 .env 與 OPENAI_API_KEY

先前提過，第一個範本其實不一定需要 OPENAI_API_KEY，但未來會用到，因此我們直接用正規方式：透過 .env。正常人不會把機密硬編碼進程式碼——我們也要盡量保持良好習慣。

為什麼用 .env

這個範本使用 .env.local 檔案，Next.js 會從中讀取環境變數。

通常版本庫會附 .env.example，或在 README 說明需要哪些變數。我們這裡的最低需求是 OPENAI_API_KEY：

OPENAI_API_KEY=sk-你的-OpenAI-金鑰

建議使用 .env.local，讓本機機密不要與正式環境設定混在一起。

重點是 .env.local 已加入 .gitignore，也就是 Git 不會看到它、也不會誤加到提交紀錄。還是請你再確認一次 .gitignore 中確實有 .env*。

在哪裡取得與如何保存 OpenAI API 金鑰

API 金鑰在 OpenAI 管理頁建立；通常以 sk- 開頭。接著遵循典型的資訊安全習慣：

• 不要把金鑰公開在 GitHub，也不要貼在聊天群組；
• 不要把它放進論壇的程式碼範例；
• 懷疑外洩就更換（金鑰輪替屬於後續安全模組的主題）。

在本講座中，我們只需確保金鑰正確放在 .env.local，並在需要時能於伺服端透過 process.env.OPENAI_API_KEY 取得。

不同作業系統的注意事項

有幾個容易踩到的坑：

• 在 Windows 上，如果你不透過 .env 設定，而是想在命令列直接指定環境變數，請用 set VAR=VALUE && 指令，而不是 export。
• 確認 .env.local 放在專案根目錄，並且檔名正確：.env 或 .env.local，不要被編輯器「好意」加上 .txt 等副檔名。

6. 第一次啟動：npm run dev 與 localhost:3000

接下來是最令人期待的部分：確認一切能編譯並順利啟動。

啟動開發伺服器

在專案根目錄執行：

npm run dev

這個指令會讓 Next.js 進入開發模式。終端機會顯示類似下列內容：

• 專案建置（開發模式會使用 Turbopack 加速）；
• 出現 Ready in Xs 之類的訊息，以及伺服器正在監聽 3000 埠；
• 顯示本機網址 http://localhost:3000。

如果看到紅色的錯誤訊息——先不要急著整段往上捲，試著讀一下：Next 通常會清楚提示缺了什麼（Node 版本、相依等等）。

在瀏覽器開啟

接著在瀏覽器開啟：

http://localhost:3000

如果一切順利，你會看到專案的起始頁。不同版本可能略有差異，但通常會有像「Your ChatGPT App」的標題或小工具的簡短說明。

這個階段我們只在意一件事：頁面能開啟、不會出現 500 錯誤，也不會噴出巨大堆疊追蹤。

之後你會看到專案可能有「首頁」（landing）和實際嵌入 ChatGPT（透過 iframe）的「小工具頁」之分。但目前對我們而言，整個網站就只是一個很昂貴的「Hello, world」展示。

全貌示意圖

為了理解全局，可以看這個簡化的示意：

+-----------------------------+
|         你的電腦            |
|                             |
|  +-----------------------+  |
|  |   Next.js 開發伺服器  |  |
|  |   (npm run dev)       |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|       瀏覽器（Chrome）      |
+-------------+---------------+

ChatGPT 與隧道會在之後才加入——目前你只是透過瀏覽器直接與本機的 Next.js 溝通。

此時 ChatGPT 還完全沒有參與。這是好事：零件越少，除錯越容易。

7. 簡易診斷：出問題時怎麼辦

經驗告訴我們：能一次成功啟動的人，多半已經在同樣環境上摔過三次了。所以來看看常見問題。

3000 埠被占用

最常見的錯誤之一：你執行 npm run dev，Next.js 提示像 EADDRINUSE: address already in use 0.0.0.0:3000。表示 3000 埠已被其他行程使用。

可能原因：

• 在其他終端機已經有這個或其他專案的 npm run dev 在執行；
• 同一個埠上跑了別的伺服器（較少見但也可能）。

解法：

• 找到並關閉舊的行程（通常關掉另一個執行 dev 伺服器的終端機就好）；
• 在另一個埠啟動開發伺服器，例如：

PORT=3001 npm run dev

在 Windows 上可以這樣：

set PORT=3001 && npm run dev

別忘了此時要在瀏覽器開啟 http://localhost:3001。

Node.js 版本過舊

如果你用的是 Node 16 或早期的 18，Next.js 16 可能會直接說不支援該版本，或 npm install 因相容性而失敗。Next 16 的文件要求至少 Node 20.9；更建議直接用最新的 LTS。

這種情況沒有別的選擇：請升級 Node。這比試著繞過 Next.js 16 的限制要快得多。升級之後，有時候刪除 node_modules 與 lock 檔（package-lock.json）再執行一次 npm install 會更乾淨，能讓相依套件針對新版本重新安裝。

npm install 發生錯誤

若安裝相依時失敗：

• 確認網路正常，且 registry.npmjs.org 沒被本地設定阻擋；
• 檢查 Node 版本（見上文）；
• 更換 Node 版本後，建議從零重建 node_modules。

大多數情況下，終端機的錯誤訊息會告訴你是哪個套件出問題，甚至會直接寫：「需要 Node >= X.Y.Z」。

環境變數沒有被讀到

有時一切能啟動，但伺服器抱怨 OPENAI_API_KEY 未設定。請依下列清單檢查：

• 檔名為 .env 或 .env.local，放在專案根目錄，且 Next.js 能讀到；
• 修改 .env 後要重啟開發伺服器，否則它會一直使用舊的環境值；
• 變數名稱必須精確為 OPENAI_API_KEY，不要拼錯。

如果你只是想先看到頁面，也可以暫時註解或停用需要金鑰的程式碼。不過在課程中，還是建議一開始就把祕密的保存方式用正確。

哪裡看日誌與錯誤

Next.js 在開發模式下的建置與執行期錯誤，會輸出到執行 npm run dev 的同一個終端機。這個階段的程式碼還不多，常見問題包括漏裝相依、.env 錯誤、或 Node 過舊。

同時也建議打開瀏覽器的 DevTools（F12）：

• Console 會提示前端是否有問題；
• Network 會顯示對 /mcp 或靜態資源的請求是否失敗（等我們接上 ChatGPT 時會用得上）。

既然你已知道在哪裡看錯誤與日誌，接著我們把流程整理成一個短小的實作腳本。

8. 小實作：你的第一個 ChatGPT App 已經跑起來了

把所有事情串在一起，做一個簡短實作。

1. 確認 node -v 至少為 20.9，最好 22 以上。
2. 確認 git --version 與 npm -v 能正常輸出版本。
3. 把官方範本複製到 study-buddy-app 資料夾（或任何你想為未來 App 取的名稱）。
4. 在該資料夾執行 npm install。
5. 建立 .env.local，並加入 OPENAI_API_KEY=...。
6. 執行 npm run dev，並在瀏覽器開啟 http://localhost:3000。

如果你都完成了——基本上你已經擁有一個最簡單的 ChatGPT App，即便目前還沒有真正連上 ChatGPT。

若想稍微「摸一下」程式碼，可以在編輯器開啟頁面的主要 React 元件（通常是 app/page.tsx），你會看到類似下面的程式碼：

export default function Page() {
  return (
    <main>
      <h1>HelloWorld — ChatGPT App</h1>
      <p>Two actions only: fetch data from <code>/api/time</code> and open an external link.</p>
    </main>
  );
}

目前不一定要修改——在接下來的講座中，我們會仔細拆解專案結構，並開始把它調整成符合我們教學情境的版本。

9. 下載與啟動範本時的常見錯誤

錯誤 1：使用非官方、來源不明的版本庫。
有時同學會在 GitHub 找到某個「很酷的 ChatGPT starter」，並從那裡開始學。但問題是，那些專案的結構、Next.js 與 Apps SDK 版本可能與本課程所依據的官方專案差異很大。在本課程中，我們會先把官方專案學紮實，再去嘗試其他人的範本。

錯誤 2：忽略 Node.js 版本要求。
「我這套 Node 16 都用了三年了，為什麼要更新？」——開發者這麼說，然後花一小時閱讀莫名其妙的建置錯誤。Next.js 16 與現代 Apps SDK 需要較新的 Node；這不是課程作者的任性，Next.js 官方文件就這麼說了。

錯誤 3：把 .env 與 node_modules 提交到版本庫。
這是經典錯誤。如果你誤把 .env 或 node_modules 從 .gitignore 移除並提交到 GitHub，輕則在 Code Review 被提醒，重則 OPENAI_API_KEY 外洩。範本已經幫你設好避免這些狀況，但檢查一下 .gitignore 的內容，別沒必要就去改它，總是好的。

錯誤 4：修改 .env 後忘記重啟開發伺服器。
Next.js 會在程序啟動時讀取環境變數。如果你把 OPENAI_API_KEY 寫進 .env.local，卻沒有重啟 npm run dev，伺服器就會持續使用舊的空值，然後你會疑惑為什麼讀不到金鑰。實務上這是最常見的問題之一，所以記得在變更 .env 後重啟 dev 伺服器。

錯誤 5：遇到同步或埠衝突問題時，靠「神奇」的重開 IDE 解決。
有時候遇到埠衝突或 Node 版本不對，開發者會開始關閉/開啟編輯器、重開電腦、祈禱等等。其實問題通常更樸實：釋放 3000 埠、更新 Node、以及閱讀終端機中的錯誤訊息。開發伺服器其實很老實地寫出它不喜歡什麼——我們要做的只是認真讀完它。