Back to Details

env-configuration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Environment configuration

环境配置

When to use: Adding or reading env vars, updating 
.env.example
, or validating config at startup with 
parseEnv
/ 
parseEnvOptional
.
适用场景： 添加或读取环境变量、更新
.env.example
，或在启动时使用
parseEnv
/ 
parseEnvOptional
验证配置。

LAT_
prefix convention

LAT_
前缀约定

All application environment variables must be prefixed with 
LAT_
so they do not collide with third-party services, Docker, or common names.
Use 
LAT_
for:
  • Database URLs and pool settings (
    LAT_DATABASE_URL
    , 
    LAT_PG_POOL_MAX
    , …)
  • Service endpoints the app reads (
    CLICKHOUSE_URL
    , 
    LAT_REDIS_HOST
    , …)
  • App ports (
    LAT_API_PORT
    , 
    LAT_WEB_PORT
    , 
    LAT_INGEST_PORT
    )
  • Auth, email, OAuth, billing, CORS (
    LAT_BETTER_AUTH_SECRET
    , 
    LAT_MAILPIT_HOST
    , …)
  • Any new variable consumed by Latitude application code
Do not use 
LAT_
for:
  • NODE_ENV
  • Docker-only init variables (
    POSTGRES_USER
    , 
    CLICKHOUSE_USER
    , …)
  • Config read only by container images (Weaviate, Redis in compose, etc.)
  • Browser-exposed Vite vars: use 
    VITE_LAT_*
     (Vite requires the 
    VITE_
    prefix)
Reference: 
.env.example
lists Docker “Services” vs “Latitude Application” (
LAT_*
) variables.
所有应用环境变量必须以
LAT_
作为前缀，避免与第三方服务、Docker或通用名称冲突。
使用
LAT_
前缀的场景：
  • 数据库URL及连接池设置（
    LAT_DATABASE_URL
    、
    LAT_PG_POOL_MAX
    等）
  • 应用读取的服务端点（
    CLICKHOUSE_URL
    、
    LAT_REDIS_HOST
    等）
  • 应用端口（
    LAT_API_PORT
    、
    LAT_WEB_PORT
    、
    LAT_INGEST_PORT
    ）
  • 认证、邮件、OAuth、计费、CORS相关配置（
    LAT_BETTER_AUTH_SECRET
    、
    LAT_MAILPIT_HOST
    等）
  • Latitude应用代码使用的任何新变量
不使用
LAT_
前缀的场景：
  • NODE_ENV
  • 仅Docker初始化使用的变量（
    POSTGRES_USER
    、
    CLICKHOUSE_USER
    等）
  • 仅容器镜像读取的配置（Weaviate、Docker Compose中的Redis等）
  • 浏览器暴露的Vite变量：请使用**
    VITE_LAT_*
    **（Vite要求前缀为
    VITE_
    ）
参考： 
.env.example
中区分了Docker“服务”变量与“Latitude应用”（
LAT_*
）变量。

.env.example
maintenance

.env.example
维护

Every new variable must appear in 
.env.example
:
  • Required: uncommented with a sensible local default (e.g. 
    LAT_API_PORT=3001
    )
  • Optional: commented with a placeholder (e.g. 
    # LAT_STRIPE_SECRET_KEY=sk_test_xxx
    )
每个新变量必须出现在
.env.example
中：
  • 必填项： 取消注释并设置合理的本地默认值（例如
    LAT_API_PORT=3001
    ）
  • 可选项： 保持注释状态并使用占位符（例如
    # LAT_STRIPE_SECRET_KEY=sk_test_xxx
    ）

Parsing in code

代码中的解析

Always use 
parseEnv
or 
parseEnvOptional
from 
@platform/env
— never 
process.env.FOO
ad hoc or unprefixed names for app config.
typescript
// ❌ Bad - unprefixed or direct access
const port = Number(process.env.PORT)

// ✅ Good - pass the variable name string (parseEnv reads process.env internally)
import { parseEnv, parseEnvOptional } from "@platform/env"
import { Effect } from "effect"

const port = Effect.runSync(parseEnv("LAT_API_PORT", "number", 3001))
const dbUrl = Effect.runSync(parseEnv("LAT_DATABASE_URL", "string"))
For where configuration is wired in apps (clients, routes), see architecture-boundaries.
请始终使用
@platform/env
中的
parseEnv
或
parseEnvOptional
——绝不要直接使用
process.env.FOO
或无前缀的名称来处理应用配置。
typescript
// ❌ 错误写法 - 无前缀或直接访问
const port = Number(process.env.PORT)

// ✅ 正确写法 - 传入变量名字符串（parseEnv内部会读取process.env）
import { parseEnv, parseEnvOptional } from "@platform/env"
import { Effect } from "effect"

const port = Effect.runSync(parseEnv("LAT_API_PORT", "number", 3001))
const dbUrl = Effect.runSync(parseEnv("LAT_DATABASE_URL", "string"))
关于应用中配置的注入位置（客户端、路由），请参考架构边界。