配置参考

本文档提供了 vibetake 项目中所有配置文件的详细说明，包括配置选项、默认值和最佳实践。

概述

vibetake 使用多个配置文件来管理不同方面的功能：

Next.js 配置 (next.config.ts) - 应用程序构建和运行时配置
Fumadocs 配置 (source.config.ts) - 文档系统配置
数据库配置 (drizzle.config.ts) - 数据库连接和迁移配置
代码质量配置 (biome.json) - 代码格式化和 linting 配置
UI 组件配置 (components.json) - shadcn/ui 组件配置
TypeScript 配置 (tsconfig.json) - TypeScript 编译器配置
认证配置 - BetterAuth 认证系统配置

Next.js 配置 (next.config.ts)

基础配置

import { createMDX } from "fumadocs-mdx/next";
import type { NextConfig } from "next";

const withMDX = createMDX({
  configPath: "source.config.ts",
});

const nextConfig: NextConfig = {
  /* config options here */
};

export default withMDX(nextConfig);

配置选项

选项	类型	默认值	说明
`experimental.turbo`	`object`	`{}`	Turbopack 配置选项
`images`	`object`	`{}`	图片优化配置
`env`	`object`	`{}`	环境变量配置

常用配置示例

const nextConfig: NextConfig = {
  // 图片优化配置
  images: {
    domains: ['example.com'],
    formats: ['image/webp', 'image/avif'],
  },
  
  // 环境变量配置
  env: {
    CUSTOM_KEY: process.env.CUSTOM_KEY,
  },
  
  // 重定向配置
  async redirects() {
    return [
      {
        source: '/old-path',
        destination: '/new-path',
        permanent: true,
      },
    ];
  },
};

错误处理

常见错误：

Module not found - 检查 MDX 配置路径是否正确
Invalid configuration - 验证配置对象结构

解决方案：

// 验证配置
const validateConfig = (config: NextConfig) => {
  if (!config) {
    throw new Error('Next.js configuration is required');
  }
  return config;
};

export default withMDX(validateConfig(nextConfig));

Fumadocs 配置 (source.config.ts)

基础配置

import { defineDocs, defineConfig } from "fumadocs-mdx/config";

export const docs = defineDocs({
  dir: "content/docs",
});

export default defineConfig();

高级配置选项

export const docs = defineDocs({
  dir: "content/docs",
  // 文档处理配置
  docs: {
    // 自定义文档转换
    transform: (page) => ({
      ...page,
      // 添加阅读时间
      readingTime: calculateReadingTime(page.content),
      // 添加最后修改时间
      lastModified: getLastModified(page.file),
    }),
  },
  // 元数据配置
  meta: {
    // 自动生成导航
    generateNav: true,
    // 搜索配置
    search: {
      enabled: true,
      placeholder: "搜索文档...",
    },
  },
});

配置验证

import { z } from 'zod';

const configSchema = z.object({
  dir: z.string().min(1, '文档目录不能为空'),
  docs: z.object({
    transform: z.function().optional(),
  }).optional(),
});

// 验证配置
export const validateDocsConfig = (config: unknown) => {
  return configSchema.parse(config);
};

数据库配置 (drizzle.config.ts)

基础配置

import { defineConfig } from "drizzle-kit";
import { config } from "dotenv";

config();

export default defineConfig({
  schema: "./src/services/database/schema.ts",
  out: "./drizzle/postgres",
  dialect: "postgresql",
  dbCredentials: {
    url: process.env.DATABASE_URL!,
  },
});

配置选项详解

选项	类型	必需	说明
`schema`	`string`	✅	数据库模式文件路径
`out`	`string`	✅	迁移文件输出目录
`dialect`	`string`	✅	数据库方言 (postgresql, mysql, sqlite)
`dbCredentials`	`object`	✅	数据库连接凭据

多环境配置

function getConfig() {
  const isDev = process.env.NODE_ENV === 'development';
  
  return {
    schema: "./src/services/database/schema.ts",
    out: isDev ? "./drizzle/dev" : "./drizzle/postgres",
    dialect: "postgresql" as const,
    dbCredentials: {
      url: process.env.DATABASE_URL!,
    },
    // 开发环境启用详细日志
    verbose: isDev,
    // 生产环境启用严格模式
    strict: !isDev,
  };
}

export default defineConfig(getConfig());

错误处理和验证

import { z } from 'zod';

const dbConfigSchema = z.object({
  schema: z.string().min(1, 'Schema 路径不能为空'),
  out: z.string().min(1, '输出目录不能为空'),
  dialect: z.enum(['postgresql', 'mysql', 'sqlite']),
  dbCredentials: z.object({
    url: z.string().url('数据库 URL 格式无效'),
  }),
});

function getValidatedConfig() {
  const config = getConfig();
  
  try {
    return dbConfigSchema.parse(config);
  } catch (error) {
    console.error('数据库配置验证失败:', error);
    throw new Error('数据库配置无效');
  }
}

认证配置 (BetterAuth)

基础配置

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";

export const auth = betterAuth({
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
  database: drizzleAdapter(db, {
    provider: "sqlite",
    schema,
  }),
  emailAndPassword: {
    enabled: true,
  },
});

高级认证配置

export const auth = betterAuth({
  // 基础配置
  baseURL: process.env.BETTER_AUTH_URL || "http://localhost:3000",
  
  // 数据库适配器
  database: drizzleAdapter(db, {
    provider: "postgresql", // 或 "mysql", "sqlite"
    schema,
  }),
  
  // 认证方式配置
  emailAndPassword: {
    enabled: true,
    // 密码要求
    password: {
      minLength: 8,
      requireUppercase: true,
      requireLowercase: true,
      requireNumbers: true,
      requireSpecialChars: true,
    },
  },
  
  // OAuth 提供商
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID!,
      clientSecret: process.env.GITHUB_CLIENT_SECRET!,
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID!,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
    },
  },
  
  // 会话配置
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 天
    updateAge: 60 * 60 * 24, // 1 天
  },
  
  // 安全配置
  security: {
    csrf: true,
    rateLimit: {
      window: 60 * 1000, // 1 分钟
      max: 100, // 最大请求数
    },
  },
});

配置验证

const authConfigSchema = z.object({
  baseURL: z.string().url('Base URL 必须是有效的 URL'),
  emailAndPassword: z.object({
    enabled: z.boolean(),
  }),
});

export const validateAuthConfig = (config: unknown) => {
  return authConfigSchema.parse(config);
};

代码质量配置 (biome.json)

格式化配置

{
  "formatter": {
    "enabled": true,
    "indentStyle": "space",
    "indentWidth": 2,
    "lineWidth": 80,
    "formatWithErrors": true,
    "useEditorconfig": true
  }
}

Linting 配置

{
  "linter": {
    "enabled": true,
    "rules": {
      "recommended": true,
      "suspicious": {
        "noSparseArray": "off",
        "noArrayIndexKey": "off"
      }
    }
  }
}

UI 组件配置 (components.json)

shadcn/ui 配置

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": true,
  "tsx": true,
  "tailwind": {
    "config": "",
    "css": "src/app/globals.css",
    "baseColor": "neutral",
    "cssVariables": true,
    "prefix": ""
  },
  "aliases": {
    "components": "@/components",
    "utils": "@/lib/utils"
  }
}

配置最佳实践

1. 环境分离

// config/index.ts
const config = {
  development: {
    database: {
      url: process.env.DEV_DATABASE_URL,
      logging: true,
    },
  },
  production: {
    database: {
      url: process.env.DATABASE_URL,
      logging: false,
    },
  },
};

export default config[process.env.NODE_ENV || 'development'];

2. 配置验证

import { z } from 'zod';

const configSchema = z.object({
  database: z.object({
    url: z.string().url(),
    logging: z.boolean(),
  }),
});

export const validateConfig = (config: unknown) => {
  try {
    return configSchema.parse(config);
  } catch (error) {
    console.error('配置验证失败:', error);
    process.exit(1);
  }
};

3. 类型安全

interface AppConfig {
  database: {
    url: string;
    logging: boolean;
  };
  auth: {
    baseURL: string;
    secret: string;
  };
}

export const createConfig = (): AppConfig => ({
  database: {
    url: process.env.DATABASE_URL!,
    logging: process.env.NODE_ENV === 'development',
  },
  auth: {
    baseURL: process.env.BETTER_AUTH_URL!,
    secret: process.env.AUTH_SECRET!,
  },
});

故障排除

常见配置错误

环境变量未设置
```
Error: DATABASE_URL is not defined
```
解决方案：检查 .env 文件是否存在且包含必要的环境变量
配置文件语法错误
```
SyntaxError: Unexpected token
```
解决方案：验证 JSON/TypeScript 语法是否正确
路径配置错误
```
Module not found: Can't resolve './config'
```
解决方案：检查文件路径是否正确，使用绝对路径或正确的相对路径

配置调试

// 添加配置调试工具
export const debugConfig = (config: any) => {
  if (process.env.NODE_ENV === 'development') {
    console.log('当前配置:', JSON.stringify(config, null, 2));
  }
};

// 使用示例
debugConfig(nextConfig);

configuration

配置参考

概述

Next.js 配置 (next.config.ts)

基础配置

配置选项

常用配置示例

错误处理

Fumadocs 配置 (source.config.ts)

基础配置

高级配置选项

配置验证

数据库配置 (drizzle.config.ts)

基础配置

配置选项详解

多环境配置

错误处理和验证

认证配置 (BetterAuth)

基础配置

高级认证配置

配置验证

代码质量配置 (biome.json)

格式化配置

Linting 配置

UI 组件配置 (components.json)

shadcn/ui 配置

配置最佳实践

1. 环境分离

2. 配置验证

3. 类型安全

故障排除

常见配置错误

配置调试

相关文档

On this page