Tạo file .env và .env.example: cú pháp, quy tắc đặt tên biến và những lỗi bảo mật hay gặp
Công cụ dựng nội dung file .env theo từng dòng khóa và giá trị, đồng thời sinh luôn bản .env.example đã xóa sạch giá trị để đưa lên kho mã nguồn. Có sẵn bộ biến mẫu cho Next.js, Node.js, React và Laravel, cho phép thêm ghi chú cho từng biến, sao chép hoặc tải về cả hai tệp. Mọi thứ chạy trong trình duyệt, giá trị bạn gõ không gửi đi đâu.
Tính năng nổi bật
- Bốn bộ biến mẫu dựng sẵn cho Next.js, Node.js, React và Laravel, bấm một lần là có ngay khung biến quen thuộc của khung ứng dụng đó
- Mỗi biến gồm ba ô riêng: tên biến, giá trị và ghi chú, ghi chú được xuất thành dòng bắt đầu bằng dấu thăng ngay phía trên biến
- Tên biến tự chuyển sang chữ in hoa và mọi ký tự ngoài chữ cái, chữ số và gạch dưới đều bị đổi thành gạch dưới
- Thêm và xóa dòng biến không giới hạn, sắp xếp lại nội dung file ngay trong khi gõ
- Hai khung xem trước cạnh nhau cập nhật tức thì: một cho .env đầy đủ giá trị, một cho .env.example đã bỏ trống giá trị
- Nút sao chép riêng cho từng tệp, tiện dán thẳng vào trình soạn thảo mà không cần tải về
- Nút tải về xuất đúng hai tên tệp .env và .env.example nên bạn khỏi phải đổi tên bằng tay
- Toàn bộ xử lý bằng JavaScript phía trình duyệt, không có bước gửi giá trị biến lên máy chủ
Vì sao nên tách cấu hình ra file .env thay vì viết thẳng vào mã
Nguyên tắc căn bản khi triển khai phần mềm là cùng một bản mã phải chạy được ở máy lập trình viên, máy kiểm thử và máy chủ thật, chỉ khác nhau ở cấu hình. Viết chuỗi kết nối cơ sở dữ liệu thẳng vào mã đồng nghĩa với việc mỗi môi trường cần một bản mã riêng, và sớm muộn cũng có người đẩy nhầm cấu hình môi trường thật lên nhánh chung. Nghiêm trọng hơn, khóa bí mật nằm trong mã sẽ nằm vĩnh viễn trong lịch sử phiên bản, xóa dòng đó ở lần nộp sau không làm nó biến mất khỏi kho. Tách ra file .env giải quyết cả hai việc: cấu hình đi theo môi trường chứ không đi theo mã, và file chứa bí mật được chặn lại từ đầu bằng danh sách bỏ qua. Phần khó chịu duy nhất còn lại là đồng bộ giữa các thành viên trong nhóm, vì file .env không lên kho thì người mới không biết dự án cần những biến nào. Đó chính là vai trò của .env.example, và cũng là lý do công cụ này sinh hai tệp cùng lúc.
Lợi ích khi sử dụng
- Không phải nhớ tên biến chuẩn của từng khung ứng dụng, bộ mẫu đã có sẵn đúng cách viết
- Bản .env.example luôn khớp với bản .env vì cả hai sinh ra từ cùng một danh sách biến
- Ghi chú đi kèm từng biến giúp người vào dự án sau hiểu ngay biến đó phục vụ việc gì
- Tên biến được chuẩn hóa tự động nên tránh lỗi khó thấy do gõ chữ thường hoặc dùng gạch ngang
- Giá trị nhạy cảm không rời khỏi trình duyệt vì công cụ không gửi dữ liệu đi bất cứ đâu
Cách dựng file .env cho dự án
- 1Bấm một trong bốn bộ mẫu nếu dự án của bạn dùng Next.js, Node.js, React hay Laravel, khung biến quen thuộc sẽ được nạp sẵn để bạn sửa cho nhanh.
- 2Điền tên biến vào ô đầu tiên, cứ gõ thường cũng được vì công cụ tự chuyển sang chữ in hoa và thay dấu gạch ngang hay khoảng trắng bằng gạch dưới.
- 3Nhập giá trị cho môi trường bạn đang làm việc và viết ghi chú ngắn giải thích biến này dùng để làm gì, ghi chú sẽ thành dòng bắt đầu bằng dấu thăng.
- 4Thêm hoặc bớt dòng cho tới khi khung xem trước bên phải hiện đúng nội dung file bạn cần, kiểm tra kỹ những biến chứa khóa bí mật.
- 5Tải hoặc sao chép bản .env vào thư mục gốc dự án, đưa bản .env.example lên kho mã nguồn, và bổ sung dòng .env vào tệp danh sách bỏ qua của Git trước khi nộp mã.
Cú pháp file .env: những quy tắc nhỏ nhưng hay gây lỗi
Mỗi dòng có dạng tên biến, dấu bằng rồi tới giá trị, không có khoảng trắng ở hai bên dấu bằng. Viết PORT = 3000 với khoảng trắng sẽ khiến một số thư viện đọc tên biến thành PORT kèm dấu cách hoặc gán giá trị có dấu cách ở đầu. Dòng bắt đầu bằng dấu thăng là ghi chú và bị bỏ qua hoàn toàn, đây là dạng công cụ dùng để xuất phần ghi chú của bạn. Giá trị chứa khoảng trắng nên bọc trong dấu nháy kép, ví dụ tên ứng dụng có hai chữ. Giá trị chứa ký tự thăng mà không bọc nháy sẽ bị nhiều thư viện cắt từ dấu thăng trở đi vì tưởng đó là ghi chú giữa dòng, điều này hay xảy ra với mật khẩu sinh ngẫu nhiên. Giá trị chứa dấu đô la có thể bị một số thư viện diễn giải như tham chiếu tới biến khác, nên hãy kiểm tra lại sau khi nạp. Cuối cùng, file .env không phải mã lệnh: không có câu lệnh, không có phép nối chuỗi, và thứ tự các dòng không quan trọng ngoại trừ trường hợp thư viện của bạn hỗ trợ tham chiếu biến đã khai báo phía trên.
Tiền tố NEXT_PUBLIC_ và REACT_APP_ nghĩa là công khai, đúng nghĩa đen
Đây là hiểu lầm gây rò rỉ khóa nhiều nhất trong các dự án web hiện nay. Với Next.js, biến có tiền tố NEXT_PUBLIC_ được thay thế thẳng vào gói mã gửi xuống trình duyệt lúc dựng bản. Với ứng dụng React tạo theo khuôn cũ, biến có tiền tố REACT_APP_ cũng vậy. Nghĩa là bất kỳ ai mở công cụ dành cho nhà phát triển của trình duyệt, tìm trong tệp JavaScript, đều đọc được nguyên văn giá trị đó. Bộ mẫu trong công cụ này cố tình chỉ đặt tiền tố công khai cho biến địa chỉ giao diện lập trình ứng dụng, vốn là thứ trình duyệt buộc phải biết. Tuyệt đối không đặt tiền tố công khai cho khóa riêng của cổng thanh toán, chuỗi kết nối cơ sở dữ liệu, khóa dịch vụ đám mây hay khóa ký phiên đăng nhập. Một dấu hiệu để tự kiểm tra: nếu biến đó cần dùng trong mã chạy phía máy chủ thì đừng thêm tiền tố; nếu bạn phải thêm tiền tố mới chạy được, rất có thể bạn đang gọi nhầm dịch vụ đó từ phía trình duyệt và cần chuyển sang gọi qua một điểm cuối trung gian.
Bốn bộ mẫu và ý nghĩa các biến bên trong
Bộ Next.js gồm địa chỉ giao diện lập trình ứng dụng công khai, chuỗi kết nối cơ sở dữ liệu dạng PostgreSQL, khóa bí mật và địa chỉ gốc dùng cho lớp xác thực. Bộ Node.js gồm biến môi trường chạy, cổng lắng nghe, chuỗi kết nối dạng MongoDB và khóa ký cho thẻ đăng nhập. Bộ React chỉ có hai biến vì ứng dụng chạy hoàn toàn phía trình duyệt, nên không có chỗ cho khóa bí mật. Bộ Laravel dài nhất với mười biến: tên ứng dụng, môi trường, khóa ứng dụng, cờ gỡ lỗi và sáu biến kết nối cơ sở dữ liệu gồm trình điều khiển, máy chủ, cổng, tên cơ sở dữ liệu, tài khoản và mật khẩu. Hai biến trong bộ mẫu cố tình để trống giá trị vì chúng phải được sinh ngẫu nhiên chứ không được gõ tay: khóa bí mật của lớp xác thực và khóa ứng dụng của Laravel. Cờ gỡ lỗi trong bộ Laravel để giá trị bật là đúng cho máy lập trình, nhưng khi đưa lên máy chủ thật bắt buộc phải tắt, vì để bật sẽ hiển thị nguyên chuỗi kết nối cơ sở dữ liệu ra trang lỗi cho bất kỳ ai truy cập.
Vai trò của .env.example và cách giữ hai tệp không lệch nhau
File .env.example là bản kê khai: nó liệt kê đầy đủ tên biến mà dự án cần, kèm ghi chú giải thích, nhưng bỏ trống toàn bộ giá trị. Đây là tệp duy nhất trong hai tệp được đưa lên kho mã nguồn. Người mới nhận dự án chỉ cần sao chép nó thành .env rồi điền giá trị của riêng mình là chạy được, không phải đi hỏi từng người xem còn thiếu biến nào. Vấn đề kinh điển là hai tệp lệch nhau theo thời gian: ai đó thêm một biến mới vào .env trên máy mình, chạy tốt, quên cập nhật bản kê khai, và người tiếp theo kéo mã về thì ứng dụng chết với một thông báo lỗi chẳng liên quan gì tới biến thiếu. Vì công cụ này sinh cả hai tệp từ cùng một danh sách nên thời điểm bạn tạo file lần đầu chắc chắn khớp. Về sau, cách giữ kỷ luật là mỗi lần thêm biến thì sửa cả hai tệp trong cùng một lần nộp mã, và nếu dự án đủ lớn thì viết một bước kiểm tra tự động so sánh danh sách tên biến giữa hai tệp trước khi cho phép hợp nhất nhánh.
File .env không phải giải pháp quản lý bí mật cho môi trường thật
Cần nói thẳng giới hạn của cách làm này. Nội dung file .env là văn bản thuần, không mã hóa, ai đọc được thư mục dự án là đọc được toàn bộ khóa. Nó phù hợp cho máy lập trình viên và cho các dự án nhỏ, nhưng khi hệ thống lên môi trường thật với nhiều người vận hành thì nên chuyển sang cơ chế quản lý bí mật của nền tảng triển khai hoặc dịch vụ lưu trữ khóa chuyên dụng, vì những nơi đó có phân quyền theo người, có nhật ký truy cập và có cơ chế xoay vòng khóa. Ba rủi ro thường gặp cần phòng ngay từ đầu: nộp nhầm file .env lên kho, và nếu lỡ thì phải coi mọi khóa trong đó là đã lộ và thay mới toàn bộ, vì xóa ở lần nộp sau không xóa được trong lịch sử; sao lưu thư mục dự án kèm cả file .env lên nơi lưu trữ dùng chung; và dán nội dung .env vào phòng chat của nhóm cho tiện. Ngoài ra, hãy thêm dòng .env vào danh sách bỏ qua của Git trước khi tạo file, chứ không phải sau.
Câu hỏi thường gặp (FAQ)
File .env đặt ở đâu trong dự án?
Thư mục gốc của dự án, ngang hàng với tệp khai báo phụ thuộc. Đa số thư viện đọc biến môi trường đều tìm từ thư mục làm việc hiện tại đi ngược lên, nên đặt sâu trong thư mục con thường không được nạp. Nếu dự án chia nhiều gói con, mỗi gói thường cần file .env riêng của nó.
Có nên đưa file .env lên Git không?
Không bao giờ. Hãy thêm dòng .env vào tệp danh sách bỏ qua ngay trước khi tạo file. Nếu đã lỡ nộp lên, xóa ở lần nộp sau là chưa đủ vì nội dung vẫn nằm trong lịch sử phiên bản và ai kéo mã về cũng đọc được. Trường hợp đó phải coi toàn bộ khóa trong file là đã lộ và thay mới hết.
Biến có tiền tố NEXT_PUBLIC_ có an toàn không?
Không, và đó là chủ ý thiết kế. Biến mang tiền tố này được nhúng thẳng vào gói mã gửi xuống trình duyệt, ai mở công cụ dành cho nhà phát triển cũng đọc được. Chỉ dùng cho những giá trị vốn đã công khai như địa chỉ giao diện lập trình ứng dụng. Khóa riêng, chuỗi kết nối cơ sở dữ liệu, khóa thanh toán thì tuyệt đối không đặt tiền tố này.
Giá trị có khoảng trắng thì viết thế nào?
Bọc trong dấu nháy kép, ví dụ tên ứng dụng gồm nhiều chữ. Nếu không bọc, một số thư viện chỉ lấy phần trước khoảng trắng đầu tiên. Tương tự, giá trị chứa dấu thăng cũng nên bọc nháy vì nhiều thư viện coi dấu thăng giữa dòng là mở đầu ghi chú và cắt bỏ phần phía sau.
Vì sao ứng dụng không nhận biến dù file .env đã có?
Ba nguyên nhân phổ biến: chưa khởi động lại tiến trình sau khi sửa file, vì biến chỉ được nạp lúc khởi động; đặt file sai thư mục; hoặc có khoảng trắng quanh dấu bằng khiến tên biến bị lệch. Với các khung dựng sẵn bản tĩnh, còn thêm nguyên nhân là biến được thay lúc dựng bản nên phải dựng lại chứ không chỉ khởi động lại.
Có cần file .env riêng cho từng môi trường không?
Nên. Thông lệ là dùng .env cho máy lập trình, còn môi trường kiểm thử và môi trường thật thì đặt biến qua cơ chế cấu hình của nền tảng triển khai. Một số khung ứng dụng còn hỗ trợ tệp riêng theo tên môi trường và nạp chồng lên nhau, hãy đọc tài liệu của khung bạn dùng để biết thứ tự ưu tiên khi cùng một biến xuất hiện ở nhiều tệp.
Công cụ có sinh giúp khóa bí mật ngẫu nhiên không?
Không. Các biến khóa bí mật trong bộ mẫu cố tình để trống vì chúng phải được sinh bằng công cụ tạo chuỗi ngẫu nhiên đủ mạnh, thường là lệnh có sẵn của chính khung ứng dụng đó. Đừng tự nghĩ ra một chuỗi trông có vẻ ngẫu nhiên, cũng đừng dùng lại một chuỗi cho nhiều dự án khác nhau.
Giá trị tôi nhập vào có bị gửi lên máy chủ không?
Không. Cả phần dựng nội dung, phần sao chép lẫn phần tải tệp về đều thực hiện bằng JavaScript ngay trong trình duyệt, không có yêu cầu mạng nào mang dữ liệu đi. Dù vậy, thói quen tốt vẫn là chỉ điền giá trị của môi trường phát triển ở đây, còn khóa của môi trường thật thì nhập trực tiếp trên nền tảng triển khai.
Tên biến nên đặt theo quy tắc nào?
Chữ in hoa toàn bộ, các từ nối bằng gạch dưới, bắt đầu bằng chữ cái, không dùng dấu gạch ngang vì nhiều môi trường dòng lệnh không đọc được. Công cụ đã tự chuẩn hóa theo đúng quy tắc này khi bạn gõ. Nên gom nhóm theo tiền tố chung như các biến cơ sở dữ liệu cùng bắt đầu bằng DB để file dễ đọc.
Có thể để giá trị trải trên nhiều dòng không?
Cách xử lý khác nhau giữa các thư viện, nên đây là chỗ dễ vỡ. Với khóa riêng dạng chứng thư nhiều dòng, hai giải pháp an toàn hơn là mã hóa nội dung sang chuỗi base64 rồi lưu thành một dòng và giải mã trong mã nguồn, hoặc đọc trực tiếp từ một tệp riêng và chỉ lưu đường dẫn tệp đó vào biến môi trường.
Hai biến trùng tên trong cùng file thì cái nào có hiệu lực?
Phần lớn thư viện lấy dòng xuất hiện đầu tiên và bỏ qua dòng sau, nhưng không phải thư viện nào cũng vậy nên đừng dựa vào hành vi đó. Công cụ không cảnh báo trùng tên, vì thế hãy rà lại khung xem trước trước khi tải về. Trùng tên biến là lỗi rất khó phát hiện vì ứng dụng vẫn chạy, chỉ là chạy với giá trị bạn không ngờ tới.
Dự án đã chạy trên máy chủ thật thì còn cần .env không?
Với hệ thống nhỏ thì vẫn dùng được, nhưng khi có nhiều người vận hành nên chuyển sang cơ chế quản lý bí mật của nền tảng triển khai hoặc dịch vụ lưu trữ khóa. Lý do là file .env chỉ là văn bản thuần không mã hóa, không phân quyền theo người và không ghi lại ai đã đọc khóa lúc nào.
Từ khóa liên quan
- tạo file .env online
- env generator
- file .env là gì
- cú pháp file .env
- biến môi trường là gì
- env example
- cách tạo .env.example
- biến môi trường Next.js
- NEXT_PUBLIC là gì
- biến môi trường Node.js
- biến môi trường React
- file .env Laravel
- APP_KEY Laravel
- gitignore file .env
- lộ khóa bí mật trên GitHub
- quản lý biến môi trường dự án
- dotenv
- cấu hình môi trường phát triển
- đặt tên biến môi trường
- bảo mật khóa API trong dự án web
