项目配置

🚀 Cheatsheet (快速执行)

目标: 5分钟内配置好所有功能，让项目跑起来

最快配置流程:

# 1. 复制环境变量模板
cp .env.local.example .env.local

# 2. 配置数据库连接
echo 'DATABASE_URL="postgresql://user:pass@host:5432/db"' >> .env.local

# 3. 生成认证密钥
echo 'AUTH_SECRET="'$(openssl rand -base64 32)'"' >> .env.local

# 4. 重启服务器
bun dev

立即生效: 保存配置后重启开发服务器，所有功能正常使用

❓ 为什么要正确配置

对 MVP 的价值:

功能完整: 正确配置后用户注册、支付、邮件都能用
避免错误: 环境变量配错会导致应用崩溃
安全保障: 密钥配置关系到数据安全
部署顺畅: 本地配置对了，部署就不会出问题

不配置的后果: 应用启动报错，功能无法使用，用户体验极差。

🤔 为什么选择这种配置方式

我们的设计原则:

环境分离: 开发/生产环境配置分离，避免误操作
功能开关: 不需要的功能可以一键关闭
类型安全: TypeScript 配置，减少配置错误
统一管理: 所有配置集中管理，修改方便

配置文件说明:

.env.local        # 敏感信息 (密钥、密码)
src/config/       # 功能配置 (开关、参数)
tailwind.config   # 样式配置 (颜色、字体)

🧠 简要原理 & 核心配置

配置加载顺序: 环境变量 → 配置文件 → 默认值 → 应用启动

最关键的配置文件:

.env.local - 数据库、API 密钥
src/config/index.ts - 功能开关和参数

配置示例:

// src/config/index.ts
export const config = {
  app: {
    name: "你的应用名",
    url: process.env.NEXTAUTH_URL,
  },
  features: {
    auth: { enabled: true },      // 启用认证
    payments: { enabled: false }, // 关闭支付
    ai: { enabled: true },        // 启用 AI
  }
}

🛠️ 实际操作步骤

1. 环境变量配置 (3分钟)

必需配置:

# .env.local
DATABASE_URL="postgresql://user:pass@host:5432/db"
AUTH_SECRET="超级长的随机字符串"
NEXTAUTH_URL="http://localhost:3000"

生成安全密钥:

# 生成 AUTH_SECRET
openssl rand -base64 32

# 或者在线生成
# https://generate-secret.vercel.app/32

2. 功能开关配置 (2分钟)

关闭不需要的功能:

// src/config/index.ts
export const features = {
  // 如果不需要组织功能
  organizations: { enabled: false },
  
  // 如果暂时不需要支付
  payments: { enabled: false },
  
  // 保留核心功能
  auth: { enabled: true },
  ai: { enabled: true },
}

3. 可选服务配置 (按需配置)

社交登录 (如果需要):

# Google OAuth (可选)
GOOGLE_CLIENT_ID="你的谷歌客户端ID"
GOOGLE_CLIENT_SECRET="你的谷歌客户端密钥"

# GitHub OAuth (可选)
GITHUB_CLIENT_ID="你的GitHub客户端ID" 
GITHUB_CLIENT_SECRET="你的GitHub客户端密钥"

邮件服务 (如果需要):

# Resend (推荐)
RESEND_API_KEY="re_your_key_here"

# 或者 SMTP
SMTP_HOST="smtp.gmail.com"
SMTP_USERNAME="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"

💡 常用配置技巧

快速开启/关闭功能

// 一键关闭所有高级功能，只保留基础功能
export const features = {
  auth: { enabled: true },          // 保留认证
  organizations: { enabled: false }, // 关闭组织
  payments: { enabled: false },     // 关闭支付
  ai: { enabled: false },           // 关闭 AI
}

环境特定配置

// 根据环境自动调整配置
const isDev = process.env.NODE_ENV === 'development'

export const config = {
  app: {
    name: isDev ? "开发版" : "正式版",
    debug: isDev,
  }
}

品牌定制

// 快速修改品牌信息
export const config = {
  app: {
    name: "你的产品名",
    description: "你的产品描述", 
    logo: "/your-logo.png",
  }
}

🎨 主题和样式配置

修改品牌颜色

// tailwind.config.ts
export default {
  theme: {
    extend: {
      colors: {
        // 修改主色调
        primary: "#你的品牌色",
        secondary: "#你的辅助色",
      }
    }
  }
}

自定义字体

// tailwind.config.ts
export default {
  theme: {
    extend: {
      fontFamily: {
        sans: ['你的字体', 'system-ui'],
      }
    }
  }
}

🔧 特定功能配置

AI 功能配置

# OpenAI (推荐)
OPENAI_API_KEY="sk-your-openai-key"

# 或者 Anthropic Claude
ANTHROPIC_API_KEY="sk-ant-your-claude-key"

支付功能配置

# Stripe (开发环境用测试密钥)
STRIPE_SECRET_KEY="sk_test_your_test_key"
STRIPE_PUBLISHABLE_KEY="pk_test_your_test_key"

文件存储配置

# AWS S3 (可选)
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_S3_BUCKET="your-bucket-name"

# 或者 Cloudinary (可选)
CLOUDINARY_CLOUD_NAME="your-cloud-name"
CLOUDINARY_API_KEY="your-api-key"

🆘 常见配置问题

问题 1: 应用启动失败

# 检查环境变量
cat .env.local

# 检查数据库连接
bun db:ping

# 重新生成 Prisma 客户端
bun db:generate

问题 2: 功能不工作

# 1. 检查功能是否启用
# 查看 src/config/index.ts 中的 features 配置

# 2. 检查环境变量是否设置
echo $OPENAI_API_KEY

# 3. 重启开发服务器
bun dev

问题 3: 样式不生效

# 清理缓存
rm -rf .next
bun dev

# 检查 Tailwind 配置
bun run build

📎 延伸阅读

配置参考:

Next.js 环境变量 - 官方环境变量指南
Tailwind CSS 配置 - 样式自定义指南

服务配置:

Google OAuth 设置 - 社交登录配置
Stripe 集成指南 - 支付系统配置

最佳实践:

12-Factor App - 应用配置最佳实践
环境变量安全 - 安全配置指南

下一步: 配置完成后，查看 [数据库设置]./database) 来初始化你的数据。 } ]


**TLDR**: 在这里定义你的定价计划，会自动在前端展示。

## 📧 邮件模板配置

### 邮件设置 (`src/lib/mail/config.ts`)

```typescript
export const mailConfig = {
  from: process.env.SMTP_FROM || 'noreply@yourdomain.com',
  replyTo: 'support@yourdomain.com',
  templates: {
    welcome: 'welcome',
    passwordReset: 'password-reset',
    invitation: 'invitation',
  }
}

自定义邮件模板

模板位置: src/lib/mail/emails/
支持格式: React 组件 + HTML
自动样式: 内联 CSS 处理

🤖 AI 功能配置

AI 提供商配置

export const aiConfig = {
  provider: 'openai', // 'openai' | 'anthropic' | 'google'
  models: {
    chat: 'gpt-4',
    embedding: 'text-embedding-3-small',
  },
  features: {
    chatbot: true,      // 聊天机器人
    textGeneration: true, // 文本生成
    imageGeneration: false, // 图片生成
  }
}

TLDR: 配置你要使用的 AI 服务商和模型。

🔒 安全配置

CORS 配置

export const corsConfig = {
  origin: process.env.NODE_ENV === 'production' 
    ? ['https://yourdomain.com']
    : ['http://localhost:3000'],
  credentials: true,
}

内容安全策略 (CSP)

export const cspConfig = {
  'default-src': ["'self'"],
  'script-src': ["'self'", "'unsafe-inline'"],
  'style-src': ["'self'", "'unsafe-inline'"],
  'img-src': ["'self'", "data:", "https:"],
}

📊 数据库配置

Prisma 配置 (`prisma/schema.prisma`)

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

连接池配置

export const databaseConfig = {
  maxConnections: 10,
  connectionTimeout: 30000,
  poolTimeout: 10000,
}

🚀 部署配置

Vercel 配置 (`vercel.json`)

{
  "buildCommand": "bun run build",
  "outputDirectory": ".next",
  "functions": {
    "app/api/**/*.ts": {
      "runtime": "nodejs18.x"
    }
  }
}

Docker 配置 (`Dockerfile`)

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN bun install
COPY . .
RUN bun run build
EXPOSE 3000
CMD ["bun", "start"]

🛠️ 开发环境配置

TypeScript 配置 (`tsconfig.json`)

严格模式: 启用所有类型检查
路径映射: @/ 指向 src/
编译目标: ES2022

ESLint 配置 (`.eslintrc.json`)

Next.js 规则: 官方推荐配置
TypeScript 支持: 类型相关检查
自动修复: 保存时自动格式化

🔧 常用配置任务

1. 关闭不需要的功能

// 关闭组织功能
organizations: {
  enabled: false,
}

// 关闭支付功能
payments: {
  enabled: false,
}

2. 修改默认语言

app: {
  locale: "en", // 改为英文
}

3. 自定义邮件发送地址

SMTP_FROM="hello@yourdomain.com"

4. 修改应用名称

app: {
  name: "你的应用名",
  description: "你的应用描述",
}

🆘 配置问题排查

常见问题

配置不生效: 重启开发服务器
环境变量未加载: 检查 .env.local 文件名
TypeScript 错误: 运行 bun type-check
功能异常: 检查对应的环境变量是否配置

调试技巧

# 检查配置是否正确
bun type-check

# 查看环境变量
echo $DATABASE_URL

# 重置配置
rm -rf .next && bun dev

下一步: 了解数据库配置来设置你的数据存储。

项目配置

On this page