Tóm tắt nhanh
- Các lần triển khai preview gặp lỗi do thiếu biến môi trường và phạm vi token.
- Tôi đã tập trung quản lý môi trường bằng cách sử dụng GitHub Environments và bí mật mã hóa.
- Đã thêm bước kiểm tra trước khi triển khai để xác thực các biến cần thiết.
Bối cảnh
Gần đây, tôi đã làm việc với một bảng điều khiển Next.js sử dụng Supabase và Vercel. Tuy nhiên, quy trình CI/CD của tôi thường xuyên gặp vấn đề — các bản build preview không thành công trong khi phát triển cục bộ vẫn hoạt động tốt. Nguyên nhân chính là do biến môi trường và phạm vi token không được truyền đúng trong Actions.
Giải pháp
1) Tập trung hóa biến môi trường và bí mật
- Sử dụng GitHub Environments (Preview/Production) cho các giá trị theo ngữ cảnh.
- Lưu trữ chỉ những gì cần thiết:
VERCEL_TOKEN,VERCEL_ORG_ID,VERCEL_PROJECT_ID,SUPABASE_URL,SUPABASE_ANON_KEY,NEXT_PUBLIC_*.
2) Bước kiểm tra trước khi triển khai
Nhằm tránh lỗi, hãy dừng ngay nếu bất kỳ biến môi trường nào bị thiếu.
3) Triển khai với token có phạm vi
Đảm bảo rằng VERCEL_TOKEN có phạm vi tối thiểu cho dự án.
4) Ví dụ về quy trình làm việc
yaml
name: Deploy Preview
on:
pull_request:
branches: [ main ]
jobs:
preview:
runs-on: ubuntu-latest
environment: preview
permissions:
contents: read
steps:
- name: Checkout
uses: actions/checkout@v4
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 20
- name: Preflight env check
run: |
required=(VERCEL_TOKEN VERCEL_ORG_ID VERCEL_PROJECT_ID SUPABASE_URL SUPABASE_ANON_KEY)
for k in "${required[@]}"; do
if [ -z "${!k}" ]; then
echo "::error::Thiếu $k"; exit 1
fi
done
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}
VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
- name: Install
run: npm ci
- name: Build
run: npm run build
env:
NEXT_PUBLIC_SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
NEXT_PUBLIC_SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
- name: Vercel deploy (Preview)
run: |
npx vercel pull --yes --environment=preview --token=$VERCEL_TOKEN
npx vercel build --token=$VERCEL_TOKEN
npx vercel deploy --prebuilt --token=$VERCEL_TOKEN
env:
VERCEL_TOKEN: ${{ secrets.VERCEL_TOKEN }}Những điều cần lưu ý
- Tránh việc trộn lẫn
NEXT_PUBLIC_*và các khóa chỉ dành cho server. - Không lưu trữ
service_rolecủa Supabase trong GitHub — hãy giữ nó ra khỏi CI trừ khi thật sự cần thiết. - Các biến môi trường của Vercel phải được tạo ra trong môi trường chính xác (Preview/Prod) hoặc pull sẽ lấy giá trị trống.
Mẹo tốt nhất
- Tổ chức hợp lý các biến môi trường: Nên nhóm các biến liên quan lại với nhau để dễ dàng quản lý.
- Thực hiện kiểm tra thường xuyên: Tạo ra các quy trình kiểm tra để phát hiện sớm các sự cố.
- Giới hạn quyền truy cập: Chỉ cấp quyền cần thiết cho token để bảo vệ tài nguyên của bạn.
Cách khắc phục sự cố
- Nếu bạn gặp lỗi liên quan đến biến môi trường, hãy sử dụng lệnh
echođể in ra giá trị biến và xác nhận xem nó có đúng không. - Kiểm tra xem tất cả các bí mật đã được cấu hình đúng trong GitHub hay chưa.
FAQ
1. Làm thế nào để kiểm tra biến môi trường trong GitHub Actions?
Bạn có thể thêm một bước kiểm tra trong quy trình làm việc của mình, sử dụng lệnh echo để in ra giá trị.
2. Tại sao token lại cần phải có phạm vi tối thiểu?
Để giảm thiểu rủi ro bảo mật và ngăn chặn truy cập không cần thiết vào các tài nguyên khác.
3. Có cần thiết phải sử dụng GitHub Environments không?
Có, điều này giúp bạn quản lý các biến môi trường theo ngữ cảnh và đảm bảo an toàn hơn trong quy trình triển khai.
Kết luận
Hy vọng rằng hướng dẫn này đã giúp bạn khắc phục các vấn đề liên quan đến môi trường Vercel và Supabase trong GitHub Actions. Đừng ngần ngại thử nghiệm và điều chỉnh quy trình của bạn cho phù hợp với dự án của mình. Nếu bạn có bất kỳ câu hỏi nào, hãy để lại ý kiến trong phần bình luận bên dưới nhé!
