SearcjGal-frontend/docs/ENV_CONFIG.md

环境变量配置指南

SearchGal 使用 .env 文件进行全局配置管理。

快速开始

1. 复制示例文件：

cp .env.example .env

2. 根据需要修改 .env 文件中的配置

3. 重启开发服务器使配置生效

配置文件

• .env - 本地环境配置（不提交到 Git）
• .env.example - 配置示例（提交到 Git）
• src/config/env.ts - 配置读取和类型定义

使用方法

方式 1：直接导入配置对象（推荐）

import { CONFIG } from '@/config'

// 使用 API 配置
const apiUrl = CONFIG.api.defaultApiUrl
console.log(apiUrl) // https://cfapi.searchgal.homes

// 使用功能开关
if (CONFIG.features.enableComments) {
  // 初始化评论系统
}

// 使用搜索配置
const cooldown = CONFIG.search.cooldown
console.log(cooldown) // 30000

方式 2：按需导入

import { API_CONFIG, FEATURE_FLAGS, SEARCH_CONFIG } from '@/config'

// API 配置
console.log(API_CONFIG.defaultApiUrl)

// 功能开关
console.log(FEATURE_FLAGS.enableVndb)

// 搜索配置
console.log(SEARCH_CONFIG.defaultMode)

方式 3：直接访问环境变量（不推荐）

// ❌ 不推荐：需要手动处理类型和默认值
const apiUrl = import.meta.env.VITE_DEFAULT_API_URL

// ✅ 推荐：使用配置对象，有类型提示和默认值
import { API_CONFIG } from '@/config'
const apiUrl = API_CONFIG.defaultApiUrl

配置分类

1. API 配置 (API_CONFIG)

API_CONFIG.defaultApiUrl      // 默认搜索 API
API_CONFIG.vndbApiUrl          // VNDB API
API_CONFIG.translateApiUrl     // AI 翻译 API
API_CONFIG.statusApiUrl        // 状态检查 API
API_CONFIG.randomImageApi      // 随机背景图片 API

2. 应用配置 (APP_CONFIG)

APP_CONFIG.name                // 应用名称
APP_CONFIG.title               // 应用标题
APP_CONFIG.description         // 应用描述
APP_CONFIG.url                 // 网站 URL

3. 功能开关 (FEATURE_FLAGS)

FEATURE_FLAGS.enablePwa        // PWA 支持
FEATURE_FLAGS.enableSw         // Service Worker
FEATURE_FLAGS.enableComments   // 评论系统
FEATURE_FLAGS.enableVndb       // VNDB 集成
FEATURE_FLAGS.enableTranslate  // AI 翻译
FEATURE_FLAGS.enableHistory    // 搜索历史
FEATURE_FLAGS.enableCache      // 缓存系统
FEATURE_FLAGS.enablePerformance // 性能监控
FEATURE_FLAGS.enableDevLogs    // 开发日志

4. 搜索配置 (SEARCH_CONFIG)

SEARCH_CONFIG.defaultMode          // 默认搜索模式
SEARCH_CONFIG.cooldown             // 搜索冷却时间（毫秒）
SEARCH_CONFIG.defaultResultsPerPage // 默认显示结果数
SEARCH_CONFIG.loadMoreCount        // 每次加载更多的数量
SEARCH_CONFIG.maxHistoryItems      // 最大历史记录数

5. 缓存配置 (CACHE_CONFIG)

CACHE_CONFIG.vndbCacheDuration     // VNDB 缓存时长（毫秒）
CACHE_CONFIG.searchCacheDuration   // 搜索结果缓存时长（毫秒）
CACHE_CONFIG.imageCacheDuration    // 图片缓存时长（毫秒）
CACHE_CONFIG.maxCacheSize          // 最大缓存数量

6. UI 配置 (UI_CONFIG)

UI_CONFIG.themePrimary         // 主题主色调
UI_CONFIG.themeAccent          // 主题强调色
UI_CONFIG.toastDuration        // Toast 通知默认时长（毫秒）
UI_CONFIG.scrollOffset         // 滚动偏移量（像素）
UI_CONFIG.scrollTopThreshold   // 回到顶部按钮显示阈值（像素）

7. 第三方服务 (THIRD_PARTY_CONFIG)

THIRD_PARTY_CONFIG.artalkServer    // Artalk 服务器地址
THIRD_PARTY_CONFIG.artalkSite      // Artalk 站点名称
THIRD_PARTY_CONFIG.busuanziEnabled // 不蒜子统计

8. 性能配置 (PERFORMANCE_CONFIG)

PERFORMANCE_CONFIG.quicklinkDelay       // Quicklink 预加载延迟（毫秒）
PERFORMANCE_CONFIG.quicklinkLimit       // Quicklink 预加载限制
PERFORMANCE_CONFIG.statusCheckInterval  // 状态检查间隔（毫秒）
PERFORMANCE_CONFIG.statusCheckTimeout   // 状态检查超时（毫秒）

9. 开发配置 (DEV_CONFIG)

DEV_CONFIG.port        // 开发服务器端口
DEV_CONFIG.hmr         // 热更新
DEV_CONFIG.sourcemap   // Source Map
DEV_CONFIG.isDev       // 是否开发环境
DEV_CONFIG.isProd      // 是否生产环境
DEV_CONFIG.mode        // 运行模式

实际使用示例

示例 1：在 Store 中使用

// src/stores/cache.ts
import { CACHE_CONFIG } from '@/config'

export const useCacheStore = defineStore('cache', () => {
  const vndbCacheDuration = ref(CACHE_CONFIG.vndbCacheDuration)
  const searchCacheDuration = ref(CACHE_CONFIG.searchCacheDuration)
  const maxCacheSize = ref(CACHE_CONFIG.maxCacheSize)
  
  // ...
})

示例 2：在组件中使用

<script setup lang="ts">
import { FEATURE_FLAGS, UI_CONFIG } from '@/config'

// 功能开关
const enableComments = FEATURE_FLAGS.enableComments

// UI 配置
const toastDuration = UI_CONFIG.toastDuration
</script>

示例 3：在 API 调用中使用

// src/api/search.ts
import { API_CONFIG } from '@/config'

export async function searchGame(query: string) {
  const response = await fetch(`${API_CONFIG.defaultApiUrl}/search`, {
    method: 'POST',
    body: JSON.stringify({ query }),
  })
  return response.json()
}

示例 4：条件渲染

<template>
  <button v-if="FEATURE_FLAGS.enableComments" @click="openComments">
    评论
  </button>
</template>

<script setup lang="ts">
import { FEATURE_FLAGS } from '@/config'
</script>

环境区分

Vite 支持多环境配置：

• .env - 所有环境加载
• .env.local - 所有环境加载，但会被 git 忽略
• .env.development - 开发环境
• .env.production - 生产环境

优先级：.env.[mode].local > .env.[mode] > .env.local > .env

注意事项

1. 环境变量必须以 VITE_ 开头才能在客户端代码中访问
2. 修改 .env 后需要重启开发服务器
3. 不要在 .env 中存储敏感信息（如密钥、密码）
4. 使用配置对象而不是直接访问环境变量，获得更好的类型支持
5. 生产环境的配置应该通过构建工具或部署平台设置

类型安全

所有配置都有完整的 TypeScript 类型支持：

import type { AppConfig } from '@/config'

// 获取完整配置的类型
const config: AppConfig = CONFIG

// 自动补全和类型检查
config.api.defaultApiUrl // ✅ 类型安全
config.api.invalidKey    // ❌ 编译错误

调试

开发环境下，配置会自动打印到控制台：

// 打开浏览器控制台查看
📦 Application Config: {
  api: {...},
  app: {...},
  features: {...},
  ...
}

可以通过 VITE_ENABLE_DEV_LOGS=false 关闭此功能。