設定驗證器
驗證設定檔與環境變數,以防止執行階段錯誤與缺少設定。
使用時機
- 處理環境變數或設定檔時
- 遇到部署或設定問題時
- 使用者提到「.env」、「config」、「環境變數」或「設定」時
操作說明
1. 尋找設定檔
搜尋以下檔案:
.env、.env.example、.env.localconfig/、config.js、config.jsonsettings.py、application.ymlappsettings.json、.env.production
2. 偵測缺少的變數
比較 .env.example 與 .env:
# 在範例中有但 .env 中沒有的變數
comm -23 <(grep -o '^[A-Z_]*' .env.example | sort) <(grep -o '^[A-Z_]*' .env | sort)
常見必要變數:
DATABASE_URL
API_KEY
SECRET_KEY
NODE_ENV
PORT
3. 驗證變數格式
檢查常見問題:
// 包含空白的值缺少引號
DATABASE_URL=postgres://localhost/db name // 錯誤
DATABASE_URL="postgres://localhost/db name" // 正確
// 缺少通訊協定
API_URL=example.com // 錯誤
API_URL=https://example.com // 正確
// 布林值寫成字串
DEBUG=true // 可能被解釋為字串
DEBUG=1 // 更明確
4. 在執行階段驗證必要變數
Node.js 範例:
const requiredEnvVars = [
'DATABASE_URL',
'API_KEY',
'JWT_SECRET'
];
const missing = requiredEnvVars.filter(v => !process.env[v]);
if (missing.length > 0) {
throw new Error(`缺少必要環境變數:${missing.join(', ')}`);
}
Python 範例:
import os
REQUIRED_ENV_VARS = [
'DATABASE_URL',
'SECRET_KEY',
'ALLOWED_HOSTS'
]
missing = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]
if missing:
raise EnvironmentError(f"缺少環境變數:{', '.join(missing)}")
5. 型別驗證
驗證型別:
const config = {
port: parseInt(process.env.PORT || '3000', 10),
debug: process.env.DEBUG === 'true',
apiUrl: new URL(process.env.API_URL), // 無效時會拋出例外
maxConnections: Number(process.env.MAX_CONNECTIONS),
};
// 驗證
if (isNaN(config.port) || config.port < 1 || config.port > 65535) {
throw new Error('PORT 必須是有效的連接埠號碼');
}
6. 產生 .env.example
從實際的 .env 建立模板:
# 移除值,保留鍵
sed 's/=.*/=/' .env > .env.example
或使用預留位置:
DATABASE_URL=postgres://user:password@localhost:5432/dbname
API_KEY=your_api_key_here
SECRET_KEY=generate_random_secret
PORT=3000
NODE_ENV=development
7. 設定結構
定義結構(使用 Joi 範例):
const Joi = require('joi');
const envSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.required(),
PORT: Joi.number()
.port()
.default(3000),
DATABASE_URL: Joi.string()
.uri()
.required(),
API_KEY: Joi.string()
.min(32)
.required(),
DEBUG: Joi.boolean()
.default(false),
}).unknown();
const { error, value } = envSchema.validate(process.env);
if (error) {
throw new Error(`設定驗證錯誤:${error.message}`);
}
module.exports = value;
8. 安全性檢查
不要提交機密:
# 檢查 .env 是否在 .gitignore 中
if ! grep -q "^\.env$" .gitignore; then
echo "警告:.env 未加入 .gitignore"
fi
# 檢查程式碼中是否有硬編碼的機密
grep -r "api_key.*=.*['\"]" --exclude-dir=node_modules
常見安全性問題:
- 硬編碼的密碼/金鑰
- 生產環境中的預設機密
- 暴露的敏感設定
- 未加密的機密
9. 依環境區分的設定
按環境組織:
.env.development
.env.staging
.env.production
.env.test
正確載入:
require('dotenv').config({
path: `.env.${process.env.NODE_ENV || 'development'}`
});
10. 記錄所有變數
建立 CONFIG.md:
# 設定
## 環境變數
### 必要
- `DATABASE_URL`:PostgreSQL 連線字串
- 格式:`postgres://user:pass@host:port/db`
- 範例:`postgres://app:secret@localhost:5432/myapp`
- `API_KEY`:第三方 API 金鑰
- 取得方式:https://dashboard.example.com
- 必要權限:讀取、寫入
### 選用
- `PORT`:伺服器連接埠(預設:3000)
- `DEBUG`:啟用除錯記錄(預設:false)
- `MAX_CONNECTIONS`:資料庫連線池大小(預設:10)
## 設定步驟
1. 將 `.env.example` 複製為 `.env`
2. 填入所有必要值
3. 執行 `npm run validate-config` 進行驗證
11. 驗證腳本
建立 scripts/validate-config.js:
const fs = require('fs');
function validateConfig() {
const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter(v => !process.env[v]);
if (missing.length > 0) {
console.error(`❌ 缺少:${missing.join(', ')}`);
process.exit(1);
}
console.log('✓ 所有必要設定變數均已存在');
}
validateConfig();
12. 最佳實務
- 絕不提交 .env:永遠將其加入 gitignore
- 維護 .env.example:保持更新
- 啟動時驗證:設定錯誤時盡早失敗
- 使用強健的預設值:合理的備援值
- 記錄一切:說明每個變數
- 輪換機密:定期更新金鑰
- 使用機密管理工具:生產環境使用 Vault、AWS Secrets Manager
- 型別檢查:驗證型別而不僅是存在與否
支援檔案
templates/config-validator.jstemplates/.env.examplescripts/generate-env-example.sh