TanStack Start - Environment Variables 环境变量

# .env
# 服务端专用（服务端函数、API 路由）
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
API_SECRET=super_secret_key

# 客户端可访问（通过 import.meta.env.VITE_*）
VITE_APP_TITLE=My App
VITE_API_URL=https://api.example.com

import { createServerFn } from '@tanstack/react-start'

export const getUser = createServerFn()
  .handler(async () => {
    // ✅ 服务端可访问所有环境变量
    const dbUrl = process.env.DATABASE_URL
    const secret = process.env.API_SECRET

    return fetch(dbUrl).then(res => res.json())
  })

export const Route = createFileRoute('/posts')({
  loader: async () => {
    // ⚠️ loader 在服务端和客户端都运行
    // 仅在 loader 内部使用服务端变量，不要暴露到客户端
    const data = await fetch(`${process.env.API_SECRET}/posts`)
    return data.json()
  }
})

function App() {
  // ✅ 客户端组件通过 import.meta.env 访问 VITE_ 前缀变量
  const apiUrl = import.meta.env.VITE_API_URL
  const title = import.meta.env.VITE_APP_TITLE

  return <div>{title} - API: {apiUrl}</div>
}

.env                # 所有情况下都加载
.env.local          # 所有情况下都加载，被 git 忽略
.env.[mode]         # 特定模式下加载（如 .env.production）
.env.[mode].local   # 特定模式下加载，被 git 忽略

import { createServerFn } from '@tanstack/react-start'

export const dbQuery = createServerFn()
  .inputValidator((query: string) => query)
  .handler(async ({ data: query }) => {
    const db = new Database(process.env.DATABASE_URL)
    return db.execute(query)
  })

# .env
AUTH_SECRET=your_jwt_secret_here
AUTH_PROVIDER_URL=https://auth.example.com
VITE_AUTH_ENABLED=true

// ✅ 好模式：服务端函数处理敏感 API 调用
export const fetchSecureData = createServerFn()
  .handler(async () => {
    const apiKey = process.env.SECRET_API_KEY // 仅服务端
    return fetch(`https://api.example.com/data?key=${apiKey}`)
  })

// ❌ 避免：在客户端暴露密钥
const response = await fetch(`https://api.example.com/data?key=${import.meta.env.VITE_SECRET_KEY}`)

function FeatureFlag() {
  const isNewUI = import.meta.env.VITE_ENABLE_NEW_UI === 'true'
  return isNewUI ? <NewUI /> : <LegacyUI />
}

/// <reference types="vite/client" />

interface ImportMetaEnv {
  readonly VITE_APP_TITLE: string
  readonly VITE_API_URL: string
  readonly VITE_ENABLE_NEW_UI: 'true' | 'false'
}

interface ImportMeta {
  readonly env: ImportMetaEnv
}

// ✅ 好模式：敏感数据留在服务端
export const secureOperation = createServerFn()
  .handler(async () => {
    const apiKey = process.env.SECRET_API_KEY
    const dbPassword = process.env.DB_PASSWORD
    // 执行敏感操作...
  })

// ❌ 避免：暴露敏感数据到客户端
// VITE_SECRET_API_KEY=super_secret  // 会被打包到客户端 bundle！

# .gitignore
.env.local
.env.*.local
.env.development.local
.env.test.local
.env.production.local