ファイル形式

env ライブラリは複数の設定ファイルフォーマットをサポートします：.env、JSON、YAML。

.env フォーマット

基本構文

# コメント
KEY=value

# 値に等記号を含む
URL=https://example.com?foo=bar

# 空行は無視される

# 無効：キーにスペースを含められない
# MY KEY=value

引用符

# 二重引用符：スペースを保持、エスケープをサポート
MESSAGE="Hello World"
PATH="/usr/local/bin"

# 単一引用符：エスケープを処理しない（バックスラッシュシーケンスをそのまま保持）
# 注意：単一引用符は変数展開を阻止しない——展開は引用符剥离後に統一して行われる
LITERAL='no escaping here: \n stays literal'

# 引用符なし
SIMPLE=value

# 空値
EMPTY=
EMPTY=""
EMPTY=''

エスケープ文字

二重引用符内でエスケープをサポートします：

# 改行
MULTILINE="line1\nline2"

# タブ
TABBED="col1\tcol2"

# 引用符
QUOTED="He said \"Hello\""

# バックスラッシュ
PATH="C:\\Users\\name"

# ドル記号
PRICE="Price: \$100"

変数展開

ExpandVariables 有効時にサポート：

# 他の変数を参照
BASE_URL=https://api.example.com
API_URL=${BASE_URL}/v1

# シンプル構文
URL=$BASE_URL/path

# デフォルト値
HOST=${HOST:-localhost}
PORT=${PORT:-8080}

# ネスト展開
SERVICE=${CLUSTER:-default}-${REGION:-us-east}

export 構文

AllowExportPrefix 有効時にサポート：

# Bash スタイルエクスポート
export KEY=value
export ANOTHER="quoted value"

YAML スタイル

AllowYamlSyntax 有効時にサポート：

# YAML スタイルのキーと値のペア
KEY: value
ANOTHER: "quoted value"

複数行の値

.env パーサーは行単位でスキャンし、各行を独立して解析し、複数行にまたがる引用符文字列をサポートしません——二重引用符の値は 1 行内で閉じる必要があり、そうでないと ErrInvalidValue を報告します。改行が必要な場合は \n エスケープを使用してください（二重引用符内のみ有効、単一引用符はエスケープを処理しません）：

# 二重引用符内の \n は改行文字として解析される
LINES="line1\nline2\nline3"
# 実際の値は 3 行テキスト：line1 / line2 / line3

# PRIVATE_KEY などの複数行証明書は \n で結合することを推奨
PRIVATE_KEY="-----BEGIN KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END KEY-----"

真の複数行文字列が必要な場合は JSON または YAML フォーマット を使用するか、カスタムパーサーで複数行サポートを拡張してください。

JSON フォーマット

基本構造

{
    "APP_NAME": "my-app",
    "APP_VERSION": "1.0.0",
    "DEBUG": true,
    "PORT": 8080
}

ネストしたオブジェクト

ネストしたオブジェクトはフラット化されます：

{
    "database": {
        "host": "localhost",
        "port": 5432
    }
}

結果：

DATABASE_HOST=localhost
DATABASE_PORT=5432

配列

配列はインデックス付きキーにフラット化されます：

{
    "ALLOWED_HOSTS": ["localhost", "example.com"],
    "PORTS": [80, 443, 8080]
}

結果：

ALLOWED_HOSTS_0=localhost
ALLOWED_HOSTS_1=example.com
PORTS_0=80
PORTS_1=443
PORTS_2=8080

配列要素へのアクセス

GetSlice[T] 関数またはドットパスでインデックスキーにアクセスします：

hosts := env.GetSlice[string]("ALLOWED_HOSTS")
port0 := env.GetInt("PORTS_0")  // 80

詳しくは GetSlice ドキュメント を参照。

型変換オプション

cfg := env.DefaultConfig()

// null を空文字列に変換
cfg.JSONNullAsEmpty = true

// 数値を文字列に変換
cfg.JSONNumberAsString = true

// ブール値を文字列に変換
cfg.JSONBoolAsString = true

深さ制限

cfg.JSONMaxDepth = 10  // 最大ネスト深度

YAML フォーマット

基本構造

APP_NAME: my-app
APP_VERSION: "1.0.0"
DEBUG: true
PORT: 8080

ネスト構造

database:
  host: localhost
  port: 5432
  credentials:
    user: admin
    password: secret

フラット化結果：

DATABASE_HOST=localhost
DATABASE_PORT=5432
DATABASE_CREDENTIALS_USER=admin
DATABASE_CREDENTIALS_PASSWORD=secret

リスト

リストはインデックス付きキーにフラット化されます：

allowed_hosts:
  - localhost
  - example.com
  - api.example.com

結果：

ALLOWED_HOSTS_0=localhost
ALLOWED_HOSTS_1=example.com
ALLOWED_HOSTS_2=api.example.com

複数行文字列

注意

YAML ブロックスカラー（リテラルブロック | とフォールドブロック >）は現在サポートされていません。パーサーは |/> を通常のスカラー文字として格納し、後続のインデント行はキーと値の解析を壊します。

改行を保持する必要がある値は、二重引用符と \n エスケープを使用してください：

description: "Line1\nLine2\nLine3"

またはカスタムパーサーでブロックスカラーサポートを拡張してください。

型変換オプション

cfg := env.DefaultConfig()

cfg.YAMLNullAsEmpty = true
cfg.YAMLNumberAsString = true
cfg.YAMLBoolAsString = true
cfg.YAMLMaxDepth = 10

フォーマット検出

自動検出

// 拡張子で検出
format := env.DetectFormat("config.json")   // FormatJSON
format = env.DetectFormat("settings.yaml")  // FormatYAML
format = env.DetectFormat(".env")           // FormatEnv

// 一致する拡張子がない場合は FormatAuto を返す（デフォルトで .env パーサーを使用）
format = env.DetectFormat("config")  // FormatAuto

フォーマット定数

const (
    FormatAuto  FileFormat = iota  // 自動検出
    FormatEnv                      // .env フォーマット
    FormatJSON                     // JSON フォーマット
    FormatYAML                     // YAML フォーマット
)

フォーマット文字列

format := env.FormatJSON
fmt.Println(format.String())  // 出力：json

ベストプラクティス

フォーマットの選択

シーン	推奨フォーマット
シンプルな設定	.env
複雑なネスト設定	JSON または YAML
他のツールとの共有	JSON
人間の可読性優先	YAML
Docker/K8s 環境	.env

ファイル命名

.env              # デフォルト設定
.env.local        # ローカル上書き（コミットしない）
.env.development  # 開発環境
.env.staging      # ステージング環境
.env.production   # 本番環境
.env.test         # テスト環境

混合使用

// 異なるフォーマットを混合使用可能
loader.LoadFiles(
    "base.env",           // 基本設定
    "database.json",      // データベース設定
    "secrets.yaml",       // 機密設定
    ".env.local",         // ローカル上書き
)

Git で無視

# 機密設定を無視
.env.local
.env.*.local
.env.production
secrets.yaml

# テンプレートを保持
!.env.example

関連ドキュメント

• マルチフォーマット設定 - マルチフォーマット読み込みガイド
• ComponentFactory API - DetectFormat 関数リファレンス
• Config API - JSON/YAML 解析オプション