Vercel: Biến môi trường khi .env không có trong Git

Hướng dẫn này dành cho một dự án đã được lưu trữ trên Vercel. Bạn cần có quyền truy cập vào phần cài đặt và hiểu ứng dụng đọc những biến nào. Ví dụ bên dưới áp dụng cho Next.js; không thể tự động dùng lại tên biến từ một framework khác. Hướng dẫn dựa trên tài liệu chính thức; chưa được thử nghiệm trên tài khoản thực tế.

Thông tin thực tế về cách sử dụng Ailoot có trong tài liệu.

Vì sao bạn không cần thêm .env vào Git#

Biến môi trường là một cài đặt có tên và giá trị mà ứng dụng nhận riêng biệt với mã nguồn. Ví dụ, tên SERVICE_API_KEY cho phép chương trình truy cập giá trị khóa của một dịch vụ bên ngoài. Đừng đưa chính khóa đó vào hướng dẫn, cuộc trò chuyện với tác nhân hoặc kho lưu trữ.

Next.js có thể tải biến từ các tệp .env* trên máy cục bộ. Tuy nhiên, tệp cục bộ và phần cài đặt dự án trong Vercel là hai vị trí riêng biệt. Nếu tệp không được đẩy lên kho lưu trữ, hãy đặt các giá trị riêng trên nền tảng lưu trữ. Mẫu create-next-app tiêu chuẩn thêm các tệp .env vào .gitignore; tài liệu Next.js cảnh báo rằng bạn hầu như không bao giờ nên đẩy chúng lên kho lưu trữ.

Nếu bạn vẫn chưa rõ có thể lưu gì trong các tệp mã nguồn, hãy bắt đầu với kiểm tra bảo mật cho dự án được xây dựng bằng AI. Ở đây, chúng ta tập trung vào một câu hỏi hẹp hơn: nơi đặt cấu hình cho một lần triển khai Vercel cụ thể.

Trước tiên, xác định ứng dụng đọc biến ở đâu#

Trước khi nhập bất kỳ giá trị nào, hãy lập danh sách tên biến, không kèm các bí mật. Với mỗi tên, bạn cần xác định ba điều: biến được dùng trong môi trường nào, mã đọc biến chạy ở đâu và khi nào cần giá trị đó.

Môi trường Development dành cho phát triển cục bộ. Preview dành cho các lần triển khai xem trước, còn Production dành cho phiên bản chính đã phát hành. Preview có thể có cài đặt cho một nhánh Git cụ thể: các cài đặt này ghi đè cài đặt Preview chung có cùng tên.

Trong dự án Next.js, các biến không có NEXT_PUBLIC_ mặc định có thể dùng trên máy chủ. Tiền tố NEXT_PUBLIC_ cho phép nhúng giá trị vào JavaScript được gửi đến trình duyệt. Cách này phù hợp với cài đặt được xác định rõ là công khai, chẳng hạn nhãn phiên bản không chứa bí mật, nhưng không phù hợp với khóa API riêng tư. Ngay cả khi không có tiền tố này, mã ứng dụng cũng không được tự ý trả bí mật về phía máy khách.

Nếu bạn chưa xác định được framework, hãy yêu cầu tác nhân nhận diện framework từ các tệp dự án. Bài so sánh Astro và Next.js có thể giúp bạn hiểu sự khác biệt; không thể áp dụng quy tắc NEXT_PUBLIC_ cho mọi ứng dụng React.

Cấu hình dịch vụ lưu trữ là một trong những công việc khi làm ứng dụng cùng tác nhân AI.

Cách thêm biến vào dự án Vercel#

Tự thực hiện các bước trong bảng điều khiển chính thức. Đừng đưa khóa thật cho tác nhân để điền vào biểu mẫu và đừng đính kèm ảnh chụp màn hình có hiển thị giá trị khóa.

1. Mở bảng điều khiển Vercel và chọn đúng dự án. Đừng chỉ dựa vào tên kho lưu trữ trùng khớp: hãy kiểm tra xem bạn đang cấu hình đúng ứng dụng mình định mở hay không.
2. Trong thanh bên cài đặt dự án, mở Environment Variables.
3. Trong trường Name, nhập tên mà ứng dụng đọc, chẳng hạn SERVICE_API_KEY. Đây là tên ví dụ; nếu mã cần tên khác, hãy dùng đúng chính tả của tên đó.
4. Trong trường Value, nhập giá trị từ nơi lưu thông tin xác thực của bạn. Đừng đưa giá trị này vào mã nguồn, cuộc trò chuyện hoặc nhật ký xác minh.
5. Chọn môi trường cần dùng cài đặt này. Dùng Preview để kiểm tra phiên bản xem trước và Production cho phiên bản chính. Đừng tự động gán một bí mật cho mọi môi trường.
6. Nếu cài đặt Preview áp dụng cho một nhánh cụ thể, hãy kiểm tra nhánh đã chọn và mọi giá trị ghi đè có cùng tên.
7. Nhấp Save.

Vercel cung cấp các biến của dự án trong cả quá trình build lẫn khi Vercel Functions phía máy chủ chạy. Tuy nhiên, việc một giá trị có thể dùng trong Vercel không có nghĩa là có thể gửi giá trị đó đến trình duyệt: điều này phụ thuộc vào mã ứng dụng và quy tắc của framework.

Vì sao cần triển khai mới sau khi nhấn Save#

Lưu một biến không làm thay đổi các lần triển khai hiện có. Tài liệu Vercel yêu cầu bạn triển khai lại dự án để cài đặt mới có hiệu lực với phiên bản bạn sử dụng.

Khi làm việc qua Git, bạn có thể tạo lần triển khai Production mới bằng cách đẩy một commit lên nhánh được chỉ định trong Production Branch, và tạo lần triển khai Preview bằng cách đẩy lên một nhánh khác. Đừng cho rằng nhánh chính luôn là main: hãy kiểm tra cài đặt của dự án. Đây nên là một lần phát hành dự án thông thường đã được thống nhất, không thêm tệp bí mật vào commit.

Sau khi bắt đầu triển khai, hãy chờ build hoàn tất rồi mở URL của lần triển khai mới. Ghi lại URL, môi trường và nhánh. Nếu kiểm tra URL cũ của một lần triển khai riêng lẻ, các cài đặt mới sẽ không xuất hiện ở đó.

Next.js có thêm một điều kiện: các tham chiếu như process.env.NEXT_PUBLIC_RELEASE_LABEL được thay bằng giá trị tương ứng trong lúc chạy next build. Giá trị được cố định sau khi build. Thay đổi cài đặt mà không build lại sẽ không viết lại JavaScript phía máy khách đã được gửi đi.

Cách kiểm tra kết quả mà không làm lộ khóa#

Bắt đầu với một ví dụ an toàn: nhãn được xác định rõ là không bí mật, tên NEXT_PUBLIC_RELEASE_LABEL và giá trị preview-check. Đây là tên và văn bản ví dụ, không phải khóa hay một phép thử đã được thực hiện ở đây. Nếu ứng dụng Next.js đọc trực tiếp biến này qua process.env.NEXT_PUBLIC_RELEASE_LABEL, ứng dụng có thể hiển thị nhãn ở vị trí dự kiến trong giao diện sau một lần build mới. Kiểm tra này chỉ xác nhận rằng cài đặt công khai đã được truyền vào.

Kiểm tra khóa riêng tư theo cách khác. Đừng hiển thị giá trị khóa, một phần giá trị, độ dài của khóa hoặc toàn bộ process.env. Đừng tạo URL công khai trả về nội dung của biến. Trước tiên, chỉ kiểm tra xem cài đặt có “tồn tại / không tồn tại” trên máy chủ hay không, sau đó kiểm tra riêng hàm ứng dụng sử dụng dịch vụ. Việc cài đặt tồn tại không chứng minh khóa hợp lệ hoặc có các quyền cần thiết.

Bạn có thể ghi lại kết quả mà không có bí mật:

• dự án, môi trường và nhánh khớp với các lựa chọn khi cấu hình;
• bạn đang kiểm tra URL của một lần triển khai mới được tạo sau khi lưu biến;
• build đã hoàn tất và hàm ứng dụng cần thiết đã chạy với dữ liệu thử nghiệm an toàn;
• bí mật không bị lộ trong trình duyệt, phản hồi API, nhật ký hoặc cuộc trò chuyện.

Nếu hàm thực hiện thanh toán, gửi tin nhắn hoặc một hành động khác có hậu quả, hãy dùng chế độ thử nghiệm được dịch vụ chỉ định. Việc kiểm tra cấu hình tự nó không cho phép thực hiện thao tác thật.

Cần kiểm tra gì nếu giá trị vẫn là undefined#

undefined có nghĩa là không nhận được giá trị tại điểm truy cập đó. Kiểm tra lần lượt tên, môi trường và phiên bản, đừng thay đổi tất cả cài đặt cùng lúc.

Sau khi kiểm tra tên, môi trường và phiên bản mới, lỗi trong hàm vẫn không chứng minh biến là nguyên nhân. Hãy điều tra lỗi cụ thể trong mã phía máy chủ mà không công khai dữ liệu chẩn đoán có chứa bí mật. Hướng dẫn này không đảm bảo sẽ giải quyết mọi phản hồi HTTP 500.

Chuyển sang máy chủ của riêng bạn cần một quy trình khác: xem hướng dẫn triển khai dự án bằng Coolify. Tên nút và các bước cấu hình của Vercel không áp dụng cho Coolify.

Truy cập Ailoot.