Tải xuống và dựng ChatGPT App (Next.js 16)

1. Giới thiệu

Mục tiêu của bài này rất đơn giản nhưng thiết yếu: đưa bạn từ con số 0 đến trạng thái “máy của tôi đang chạy ChatGPT App cục bộ, tôi thấy trang trong trình duyệt và không có gì bị sập”.

Chúng ta sẽ không đi quá sâu vào mã Next.js, chưa bật Dev Mode trong ChatGPT và cũng chưa bật tunnel — đó là các bài kế tiếp của mô-đun. Hôm nay tập trung vào ba việc:

1. Chuẩn bị môi trường: Node.js, npm, Git, trình chỉnh sửa, các kiểm tra cơ bản để Next.js 16 không “chết” trên phiên bản Node của bạn.
2. Tải ChatGPT App hoạt động trên Next.js 16: hoặc qua git clone, hoặc qua GitHub template/CLI.
3. Cài đặt phụ thuộc, cấu hình .env với OPENAI_API_KEY và chạy npm run dev, đảm bảo http://localhost:3000 của bạn “khỏe mạnh”.

Nếu cuối bài bạn thấy trang khởi đầu của mẫu trong trình duyệt và dev server trong terminal không có lỗi đỏ — có thể coi là bạn đã có ChatGPT App chạy được.

2. Môi trường phát triển tối thiểu

Bắt đầu với hạ tầng. Không có nó, mọi LLM “xịn” cũng không giúp được — Next.js đơn giản là không khởi chạy.

Node.js và npm

Mẫu Apps SDK hiện đại trên Next.js 16 yêu cầu Node mới. Hướng tới nhánh LTS — hiện tại, ví dụ, là Node 24 LTS. Phiên bản tối thiểu chấp nhận được — 20.9, từ bản đó Next.js 16 được hỗ trợ chính thức.

Kiểm tra phiên bản trong terminal:

node -v
npm -v

Nếu thay vì v24.x.x gọn gàng bạn thấy, chẳng hạn, v16.13.0, rất có thể mẫu sẽ không cài nổi phụ thuộc hoặc Next.js sẽ phàn nàn: phiên bản Node đó không được hỗ trợ.

Bạn có thể cập nhật “đơn giản” — qua trình cài đặt chính thức của Node.js cho hệ điều hành của bạn — hoặc, nếu bạn đã quen trên Linux/macOS, qua nvm/fnm. Trong phạm vi khóa học, chúng ta không đi sâu vào trình quản lý phiên bản; điều quan trọng là có bản LTS hoạt động.

Git

Chúng ta cần Git để lấy mẫu và sau này commit thay đổi của bạn. Kiểm tra:

git --version

Nếu lệnh không tìm thấy, hãy cài Git (trình cài đặt cho Windows, Homebrew trên macOS, trình quản lý gói trên Linux). Để chạy App thì Git không quá bắt buộc, nhưng làm việc mà không có nó vào năm 2025 — cũng như viết TypeScript mà không biết interface là gì.

Trình chỉnh sửa mã

Khuyến nghị mặc định — WebStorm. JavaRush có plugin riêng để bạn giải bài chỉ với vài cú nhấp. Thực tế đây là “tiêu chuẩn de facto” cho frontend và Node.

Bạn có thể dùng VS Code, khi đó nên cài các extension cơ bản:

• hỗ trợ TypeScript/JavaScript;
• ESLint (mẫu thường đã cấu hình sẵn linter).

Điều này sẽ giúp bạn khi bắt đầu chỉnh mã của mẫu.

Tài khoản OpenAI / ChatGPT và API key

Đối với bài này, bạn chỉ cần có quyền truy cập ChatGPT trong trình duyệt (bằng tài khoản của bạn). Chúng ta sẽ kết nối Dev Mode sau, nhưng tốt nhất hãy đảm bảo bạn đăng nhập được vào giao diện web và có tab tính năng dành cho nhà phát triển (Plus/Team/Enterprise tùy chính sách hiện hành của OpenAI).

Sau này sẽ cần OpenAI API key (OPENAI_API_KEY). Dự án đầu tiên của chúng ta có thể chạy mà chưa cần: UI khởi đầu hoàn toàn tĩnh. Nhưng chúng ta vẫn sẽ dùng key ngay trong bài này và đặt nó vào file .env — bên dưới sẽ xem chi tiết và vì sao cách đó an toàn hơn.

Lấy key tại bảng điều khiển OpenAI, lưu dưới dạng secret, không đưa vào repository và nhìn chung hãy đối xử với nó như số hộ chiếu, thậm chí còn cẩn trọng hơn.

3. Lấy ChatGPT App hoạt động ở đâu

Giờ đến phần dễ chịu nhất: lấy một dự án khởi đầu đã được cấu hình sẵn như ChatGPT App.

Vì sao chọn dự án này

Đây là một dự án rất đơn giản trên Next.js 16, kết hợp hai vai trò trong cùng một repository: widget UI và máy chủ MCP.

Cấu trúc đã chuẩn bị sẵn:

• có trang React sẽ được render như widget;
• có endpoint của máy chủ MCP để ChatGPT gọi vào cho công cụ;
• có cấu hình Next.js sẵn (bao gồm chi tiết quan trọng như assetPrefix để tải asset đúng trong iframe của ChatGPT).

Như vậy tốt hơn nhiều so với tự lắp ghép từ đầu.

Phương án 1: clone repository Git

Cách trực tiếp nhất:

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

Tên repository có thể khác đôi chút trong tương lai, nên trước khi copy lệnh bạn nên kiểm chứng liên kết mới nhất trong tài liệu chính thức hoặc phần bình luận dưới bài này.

Lệnh git clone sẽ tạo thư mục my-chatgpt-app có đầy đủ nội dung mẫu và Git repository đã cấu hình sẵn.

Phương án 2: nút “Use this template” trên GitHub

Nếu bạn muốn có repository riêng trên GitHub ngay từ đầu, có thể:

1. Mở trang mẫu trên GitHub.
2. Nhấn nút “Use this template”.
3. Tạo repository của riêng bạn dựa trên mẫu, ví dụ username/study-buddy-chatgpt-app.
4. Sau đó clone repository của chính bạn.

Về bản chất, kết quả là như nhau: bạn sẽ có thư mục cục bộ với mã của mẫu, nhưng Git remote trỏ không phải vào repository của CodeGym mà là của bạn.

Phương án 3: mẫu CLI

Rất có thể trong tương lai sẽ có công cụ CLI chính thức từ OpenAI, kiểu như:

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

Hiện vẫn chưa có, vì ứng dụng cho ChatGPT mới bắt đầu phát triển. Nhưng rất có thể đến lúc bạn đọc bài này, đã có thứ tương tự. Hãy kiểm tra tài liệu chính thức của Apps SDK để tìm lệnh như vậy.

Logic tương tự: CLI chỉ tải về và bung ra mẫu tương tự hoặc rất giống. Trước đây đã có công cụ như vậy để tạo plugin cho ChatGPT, nên sau một thời gian, nhiều khả năng sẽ có cho ứng dụng.

4. Cài đặt phụ thuộc và cái nhìn đầu tiên về dự án

Giả sử bạn đã có thư mục my-chatgpt-app với dự án hoạt động. Đến lúc cài dependencies.

npm install

Chuyển vào thư mục dự án và cài dependencies:

cd my-chatgpt-app
npm install

Script sẽ đọc package.json, trong đó đã khai báo các gói cần thiết: Next.js, React, Tailwind, Apps SDK và MCP SDK (@modelcontextprotocol/sdk).

Kết quả sẽ xuất hiện thư mục node_modules — “con quái vật” hàng trăm MB mà chúng ta không bao giờ commit vào Git. Thư mục này thường đã được thêm vào .gitignore trong mẫu, nên không cần cấu hình gì thêm.

Nếu trong quá trình cài đặt phụ thuộc có gì đó lỗi, đừng hoảng: phần bên dưới sẽ có chẩn đoán các vấn đề hay gặp.

Nhìn nhanh nội dung

Hiện tại chưa cần đi sâu vào cấu trúc thư mục — đó là chủ đề bài sau, nơi chúng ta sẽ phân tích chi tiết mọi thứ nằm ở đâu. Nhưng cũng hữu ích nếu liếc qua thư mục gốc dự án:

• package.json — danh sách dependencies và scripts.
• next.config.ts — cấu hình Next.js với các tùy chỉnh bổ sung để chạy bên trong ChatGPT.
• tsconfig.json — cấu hình TypeScript.
• app/ — nơi chứa mã UI chính và các route MCP.

Lần tới chúng ta sẽ biến “khu rừng tối” này thành một bản đồ dễ hiểu.

5. Cấu hình .env và OPENAI_API_KEY

Trước đó chúng ta đã nhắc rằng mẫu đầu tiên không cần OPENAI_API_KEY, nhưng nó sẽ được dùng trong tương lai, nên hãy làm ngay cho “đúng bài”: qua .env. Làm đúng thì không hardcode secret vào code — chúng ta cũng sẽ làm như vậy.

Tại sao cần .env

Mẫu sử dụng file môi trường .env.local, và Next.js sẽ nạp các biến môi trường từ đó.

Thông thường trong repository sẽ có .env.example hoặc README mô tả cần đặt những biến nào. Trong trường hợp của chúng ta, tối thiểu sẽ là OPENAI_API_KEY:

OPENAI_API_KEY=sk-khoa-cua-ban-tu-OpenAI

Khuyến nghị dùng .env.local để secret cục bộ không lẫn với cấu hình production.

Quan trọng là .env.local đã được thêm vào .gitignore, tức là Git sẽ không thấy và vô tình thêm nó vào commit. Dù vậy, vẫn nên kiểm tra lại rằng trong .gitignore thực sự có dòng .env*.

Lấy ở đâu và lưu OpenAI API key thế nào

API key được tạo trong bảng điều khiển OpenAI; nó thường bắt đầu bằng sk-. Sau đó làm theo “vệ sinh” chuẩn của IT:

• không công khai key trên GitHub và không gửi vào các nhóm chat;
• không dán nó vào ví dụ mã trên diễn đàn;
• nếu nghi ngờ rò rỉ — hãy thay (luân phiên key — chủ đề của các mô-đun về bảo mật).

Trong bài này, điều quan trọng là key được đặt đúng trong .env.local và truy cập được qua process.env.OPENAI_API_KEY ở phía server khi cần.

Lưu ý theo hệ điều hành

Có vài lưu ý nhỏ rất dễ vấp phải:

• Trên Windows, nếu bạn muốn đặt biến môi trường không qua .env mà trực tiếp trong dòng lệnh, bạn sẽ phải dùng set VAR=VALUE && command, chứ không phải export.
• Đảm bảo .env.local nằm ở thư mục gốc dự án và tên đúng: .env hoặc .env.local, không phải .txt hay các “cải tiến” khác từ trình soạn thảo.

6. Chạy lần đầu: npm run dev và localhost:3000

Giờ đến phần dễ chịu nhất: kiểm tra mọi thứ đã build xong và dự án khởi chạy được.

Khởi chạy dev server

Ở thư mục gốc dự án, chạy:

npm run dev

Lệnh này chạy Next.js ở chế độ phát triển. Trong terminal bạn sẽ thấy đại khái:

• quá trình build dự án (dùng Turbopack cho chế độ dev nhanh);
• dòng như Ready in Xs và thông báo server lắng nghe port 3000;
• địa chỉ http://localhost:3000 là URL cục bộ.

Nếu xuất hiện thông báo lỗi màu đỏ — đừng lướt vội lên trên, hãy đọc thử: Next thường gợi ý khá tốt xem nó thiếu gì (phiên bản Node, phụ thuộc, v.v.).

Mở trong trình duyệt

Sau đó mở trong trình duyệt:

http://localhost:3000

Nếu mọi thứ ổn, bạn sẽ thấy trang khởi đầu của dự án. Ở các phiên bản khác nhau, trang có thể hơi khác, nhưng thường có tiêu đề kiểu “Your ChatGPT App” hoặc mô tả tối thiểu của widget.

Ở bước này, điều quan trọng chỉ là: trang mở được, không đổ 500 và không hiện stack trace khổng lồ.

Sau này ta sẽ thấy dự án có thể khác nhau giữa “trang chính” (landing) và trang widget thực sự được nhúng vào ChatGPT qua iframe. Nhưng hiện tại với chúng ta, cả site chỉ là một cách rất “đắt đỏ” để hiển thị “Hello, world”.

Bức tranh tổng quan

Để nắm bức tranh chung, hãy xem sơ đồ đơn giản:

+-----------------------------+
|      Máy tính của bạn       |
|                             |
|  +-----------------------+  |
|  |  dev server Next.js   |  |
|  |  (npm run dev)        |  |
|  +----------+------------+  |
|             |               |
|   http://localhost:3000     |
|             |               |
|    Trình duyệt (Chrome)     |
+-------------+---------------+

ChatGPT và tunnel sẽ xuất hiện sau — hiện bạn giao tiếp trực tiếp với Next.js cục bộ qua trình duyệt.

ChatGPT hiện chưa tham gia gì cả. Và như vậy là tốt: ít thành phần chuyển động hơn — dễ debug hơn.

7. Chẩn đoán nhanh: làm gì khi có sự cố

Thực tế cho thấy: nếu ai đó chạy được ngay từ lần đầu — rất có thể trước đó họ đã “toang” ba lần với cùng cấu hình. Vậy hãy xem các vấn đề điển hình.

Cổng 3000 đang bận

Một trong những lỗi phổ biến: bạn chạy npm run dev, còn Next.js báo kiểu EADDRINUSE: address already in use 0.0.0.0:3000. Tức là cổng 3000 đã bị tiến trình khác chiếm.

Nguyên nhân có thể:

• ở terminal khác đã có npm run dev đang chạy từ dự án này hoặc dự án khác;
• có server khác dùng cùng cổng (ít gặp hơn nhưng vẫn có).

Giải pháp:

• tìm và dừng tiến trình cũ (thường chỉ cần đóng terminal đang chạy dev server);
• chạy dev server ở cổng khác, ví dụ:

PORT=3001 npm run dev

Trên Windows sẽ như sau:

set PORT=3001 && npm run dev

Khi đó đừng quên mở http://localhost:3001 trong trình duyệt.

Node.js quá cũ

Nếu bạn dùng Node 16 hoặc 18 giai đoạn đầu, Next.js 16 có thể thẳng thừng báo phiên bản đó không được hỗ trợ, hoặc npm install sẽ thất bại vì không tương thích. Tài liệu Next 16 yêu cầu Node tối thiểu 20.9, tốt nhất là bản LTS mới.

Trường hợp này thì không có lựa chọn khác: hãy cập nhật Node. Nhanh hơn nhiều so với cố lách hạn chế của Next.js 16. Sau khi nâng cấp, đôi khi nên xóa thư mục node_modules và file lock (package-lock.json) rồi chạy lại npm install để dependencies khớp với phiên bản mới.

Lỗi khi npm install

Nếu cài đặt phụ thuộc bị lỗi:

• đảm bảo internet hoạt động và registry.npmjs.org không bị chặn bởi cấu hình cục bộ;
• kiểm tra phiên bản Node (xem ở trên);
• khi đổi phiên bản Node, nên cài lại node_modules từ đầu.

Phần lớn trường hợp, thông báo lỗi trong terminal sẽ cho biết gói nào gây vấn đề, và thường ghi rõ: “cần Node >= X.Y.Z”.

Biến môi trường không được nạp

Đôi khi mọi thứ khởi chạy, nhưng server báo OPENAI_API_KEY chưa được đặt. Khi đó kiểm tra theo danh sách sau:

• file tên .env hoặc .env.local, nằm ở thư mục gốc dự án và Next.js thấy được;
• sau khi thêm/sửa .env phải khởi động lại dev server, nếu không nó sẽ dùng các giá trị môi trường cũ;
• tên biến chính xác là OPENAI_API_KEY, không có lỗi chính tả.

Nếu bạn chỉ muốn mở trang dự án, có thể tạm thời comment hoặc tắt những phần mã đòi hỏi key, nhưng trong khuôn khổ khóa học tốt hơn là học cách lưu trữ secret đúng ngay từ đầu.

Xem log và lỗi ở đâu

Mọi lỗi build và runtime của Next.js ở chế độ dev sẽ in ra cùng terminal nơi bạn chạy npm run dev. Ở giai đoạn này mã còn ít, nên các vấn đề điển hình là thiếu phụ thuộc, .env sai hoặc Node quá cũ.

Ngoài ra, hãy mở DevTools trong trình duyệt (F12):

• tab Console sẽ gợi ý nếu frontend có vấn đề;
• Network sẽ hiển thị nếu một số request tới /mcp hoặc static bị lỗi (sau này sẽ hữu ích khi kết nối ChatGPT).

Giờ khi bạn đã biết tìm lỗi và log ở đâu, hãy gom lại thành một kịch bản thực hành ngắn.

8. Thực hành nhỏ: ChatGPT App đầu tiên của bạn đã chạy

Gom mọi thứ lại trong một kịch bản ngắn.

1. Kiểm tra node -v ít nhất là 20.9, tốt nhất 22+.
2. Kiểm tra git --version và npm -v có phản hồi.
3. Clone mẫu chính thức vào thư mục study-buddy-app (hoặc tên bạn muốn cho App tương lai).
4. Trong thư mục này chạy npm install.
5. Tạo .env.local với OPENAI_API_KEY=....
6. Chạy npm run dev và mở http://localhost:3000 trong trình duyệt.

Nếu mọi thứ ổn — có thể coi là bạn đã có ChatGPT App đơn giản nhất, dù hiện chưa kết nối ChatGPT.

Để “chạm” một chút vào mã, bạn có thể mở trong trình chỉnh sửa React component chính của trang (thường là app/page.tsx) và sẽ thấy thứ gì đó rất giống đoạn mã sau:

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>
  );
}

Chưa cần chỉnh sửa — ở một trong các bài tiếp theo, chúng ta sẽ phân tích cấu trúc dự án và bắt đầu điều chỉnh cho kịch bản học tập của mình.

9. Lỗi thường gặp khi tải và chạy mẫu

Lỗi №1: dùng repository “lạ” thay vì dự án chính thức.
Đôi khi học viên tìm trên GitHub một “starter ChatGPT rất ngầu” và bắt đầu khóa học với nó. Vấn đề là cấu trúc, phiên bản Next.js và Apps SDK ở đó có thể rất khác dự án chính thức mà khóa học dựa vào. Trong khuôn khổ khóa học này, trước tiên chúng ta làm chủ dự án chính thức, sau đó mới thử nghiệm với các mẫu khác.

Lỗi №2: bỏ qua yêu cầu về phiên bản Node.js.
“Máy tôi chạy Node 16 ba năm rồi, sao phải nâng cấp?” — nhà phát triển nói và rồi ngồi một giờ đọc các lỗi build kỳ lạ. Next.js 16 và Apps SDK hiện đại yêu cầu Node mới, và đây không phải ý thích của tác giả khóa học: tài liệu Next.js ghi rõ điều đó.

Lỗi №3: commit .env và node_modules vào repository.
Kinh điển. Nếu bạn vô tình bỏ .env hoặc node_modules khỏi .gitignore và commit tất cả lên GitHub, tốt nhất là bạn sẽ bị nhắc nhở ở code review, tệ nhất — OPENAI_API_KEY sẽ bị lộ. Mẫu đã được cấu hình để tránh điều này, nhưng luôn hữu ích khi kiểm tra nội dung .gitignore và không sửa nó khi không cần thiết.

Lỗi №4: quên khởi động lại dev server sau khi đổi .env.
Next.js đọc biến môi trường khi tiến trình khởi chạy. Nếu bạn thêm OPENAI_API_KEY vào .env.local nhưng không khởi động lại npm run dev, server sẽ tiếp tục chạy với giá trị môi trường cũ, còn bạn sẽ thắc mắc vì sao key “không thấy”. Trên thực tế đây là một trong những nguyên nhân gây nhầm lẫn phổ biến nhất, nên đừng quên khởi động lại dev server sau khi sửa .env.

Lỗi №5: cố giải quyết vấn đề đồng bộ và cổng bằng các “mẹo” khởi động lại IDE.
Đôi khi khi xung đột cổng hoặc phiên bản Node sai, lập trình viên bắt đầu đóng/mở trình chỉnh sửa, khởi động lại máy, cầu nguyện, v.v. Trong khi vấn đề thường được giải quyết giản dị hơn nhiều: giải phóng cổng 3000, cập nhật Node và đọc lại thông báo lỗi trong terminal. Dev server viết khá “thật thà” điều nó không thích — chỉ cần chịu khó đọc.