快速入门指南

5分钟让你的 HackathonWeekly 代码跑起来 - 完整的开发者指南

重要提醒

社区源码暂未公开，敬请期待！如有合作需求可联系: makerjackie，注明来意

HackathonWeekly 社区代码 - 完整开发指南

这是一个基于 Next.js 的社区代码仓库，欢迎贡献 Pull Request！

🚀 5分钟快速上手

前置要求

Node.js 20+: 下载地址 (项目要求 Node.js 20 或更高版本)
bun 9.3.0+: 更快的包管理器 npm install -g bun
PostgreSQL 数据库: 推荐 Neon 或 Supabase

安装步骤

# 1. 克隆项目 （源码暂未开源，敬请期待）
git clone https://github.com/hackathonweekly.git
cd community

# 2. 安装依赖
bun install

# 3. 复制环境变量文件
cp .env.local.example .env.local

# 4. 配置数据库连接
# 编辑 .env.local 文件，设置数据库 URL

# 5. 初始化数据库
bun db:push

# 6. 启动开发服务器
bun dev

# 注意生成环境中使用 prisma migrate deploy 而不是 db push

打开 http://localhost:3000 查看结果！

验证安装

看到以下内容说明安装成功：

✅ 首页正常显示
✅ 可以点击"登录"按钮
✅ 注册页面可以访问
✅ 没有控制台错误

🔧 环境配置详解

必需配置

在 .env.local 文件中设置：

# 数据库连接（必填）
DATABASE_URL="postgresql://username:password@host:port/database"

# Better Auth 密钥（必填，随机生成）
BETTER_AUTH_SECRET="your-random-secret-key"  # 运行: openssl rand -base64 32

# 应用地址
BETTER_AUTH_URL="http://localhost:3000"

可选配置

社交登录:

# Google OAuth
GOOGLE_CLIENT_ID="your-google-client-id"
GOOGLE_CLIENT_SECRET="your-google-client-secret"

# GitHub OAuth  
GITHUB_CLIENT_ID="your-github-client-id"
GITHUB_CLIENT_SECRET="your-github-client-secret"

AI 功能:

# OpenAI API
OPENAI_API_KEY="sk-..."

文件存储:

# AWS S3 (可选)
AWS_ACCESS_KEY_ID="your-access-key"
AWS_SECRET_ACCESS_KEY="your-secret-key"
AWS_REGION="us-east-1"
NEXT_PUBLIC_BUCKET_NAME="your-bucket-name"

邮件服务:

# SMTP 设置（用于发送验证邮件）
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USERNAME="your-email@gmail.com"
SMTP_PASSWORD="your-app-password"

🏗️ 项目结构

src/
├── app/                    # 页面路由（Next.js App Router）
│   ├── (public)/           # 公开页面路由组
│   │   ├── [locale]/       # 国际化路由
│   │   ├── blog/           # 博客页面
│   │   ├── docs/           # 文档页面
│   │   ├── contact/        # 联系页面
│   │   └── legal/          # 法律页面
│   ├── (app)/              # 应用功能路由组
│   │   ├── app/            # 应用主界面
│   │   └── auth/           # 认证页面
│   ├── api/                # API 路由
│   │   ├── auth/           # 认证 API
│   │   ├── payments/       # 支付 API
│   │   └── ai/             # AI 功能 API
│   └── image-proxy/        # 图片代理
├── components/ui           # 基础 UI 组件（shadcn/ui）
├── modules/                # 模块化组件系统
│   ├── marketing/          # 营销页面组件
│   │   ├── home/           # 首页组件
│   │   ├── blog/           # 博客组件
│   │   └── docs/           # 文档组件
│   ├── dashboard/               # dashboard 功能组件
│   │   ├── auth/           # 认证组件
│   │   ├── dashboard/      # 仪表板组件
│   │   ├── organizations/  # 组织管理
│   │   └── ai/             # AI 功能组件
│   ├── shared/             # 通用组件
│   ├── analytics/          # 分析组件
│   └── i18n/               # 国际化组件
├── config/                 # 应用配置
│   ├── index.ts            # 主配置文件
│   └── types.ts            # 配置类型定义
├── lib/                    # 核心功能库
│   ├── auth/               # Better Auth 认证系统
│   ├── database/           # Prisma 数据库
│   │   └── prisma/         # Prisma schema 和查询
│   ├── payments/           # Stripe 支付系统
│   ├── ai/                 # AI 功能集成
│   ├── mail/               # 邮件服务
│   ├── storage/            # 文件存储
│   ├── i18n/               # 国际化配置
│   ├── logs/               # 日志系统
│   └── utils.ts            # 工具函数
├── server/                 # Hono 服务端
│   ├── app.ts              # 服务端应用
│   ├── routes/             # API 路由定义
│   ├── middleware/         # 中间件
│   └── lib/                # 服务端工具
└── styles/                 # 样式文件
    ├── globals.css         # 全局样式
    ├── tailwind-animate.css # 动画样式
    └── theme.css           # 主题样式

🔧 核心功能模块

在正式开始开发之前，我们强烈建议您通读一下整个仓库的代码，这会避免很多重复的开发，并且让您可以更好的基于当前的代码，在合适的位置继续添砖加瓦。

1. 用户认证系统 (Better Auth)

📍 代码位置: src/lib/auth/
🔑 登录方式: 邮箱密码、Google、GitHub、魔术链接、通行密钥、双因素认证
⚙️ 配置: src/config/index.ts 中的 auth 部分
🔐 特性: 会话管理、密码重置、邮箱验证、用户封禁
📚 详细文档: 认证系统配置

2. 数据库管理 (Prisma + PostgreSQL)

📍 Schema: src/lib/database/prisma/schema.prisma
🗄️ 数据模型: 用户、组织、会员、邀请、购买、AI 聊天等
🛠️ 常用命令:
- bun db:push - 同步数据库结构（单人快速开发使用）
- bun db:studio - 可视化管理工具
- bun db:generate - 生成 Prisma 客户端
- bun db:migrate - 数据库迁移（多人协作 & 生产环境中使用）
📚 详细文档: 数据库配置

3. 支付系统 (Stripe)

📍 代码位置: src/lib/payments/
💳 支持: Stripe 支付（订阅 + 一次性付款）
📋 计划配置: src/config/index.ts 中的 payments.plans
💰 内置计划: Free、Pro（月付/年付）、Lifetime、Enterprise
🎯 功能: 基于座位的计费、试用期、Webhook 处理
📚 详细文档: 支付系统

4. 组织管理

📍 代码位置: src/modules/dashboard/organizations/
👥 功能: 创建组织、邀请成员、角色管理、组织计费
⚙️ 配置: src/config/index.ts 中的 organizations 部分
🔐 权限: 支持多种角色和权限控制
📚 详细文档: 组织管理

5. AI 功能集成

📍 代码位置: src/modules/dashboard/ai/ 和 src/lib/ai/
🤖 支持: OpenAI GPT 模型、AI SDK React
💬 功能: AI 聊天、流式响应、聊天历史
🗄️ 存储: 聊天记录存储在数据库中
📚 详细文档: AI 功能

6. 国际化支持 (next-intl)

📍 配置文件: src/modules/i18n/ 和 src/lib/i18n/
🌐 支持语言: 简体中文（默认）、英文、德语
💰 货币支持: CNY（人民币）、USD（美元）
🔄 切换: 页面右上角语言选择器
🍪 存储: 使用 Cookie 保存用户语言偏好
📚 详细文档: 国际化配置

🎨 UI 组件系统

🧩 组件库: 基于 shadcn/ui + Tailwind CSS 4.x
📱 响应式: 移动端优先设计
🌙 主题: 支持亮色/暗色模式（next-themes）
💅 定制: 通过 tailwind.config.ts 修改样式
🎯 路径别名: 使用 @/components/ui/* 快速导入组件
✨ 动画: 内置 Tailwind CSS 动画支持
🎨 图标: Lucide React 图标库
📦 组件: Button、Dialog、Dropdown、Table 等完整组件集

📚 开发指南

添加新页面

路由组织: 在 src/app/(public)/ 或 src/app/(app)/ 下创建页面
文件结构: 创建 page.tsx、layout.tsx（可选）、loading.tsx（可选）
国际化: 使用 [locale] 动态路由支持多语言
组件: 使用 TypeScript 和 React Server Components
样式: 使用 Tailwind CSS 类名

添加新组件

位置选择:
- 通用组件 → src/modules/shared/
- UI 组件 → src/modules/ui/
- 业务组件 → src/modules/marketing/ 或 src/modules/dashboard/
类型定义: 使用 TypeScript interfaces 定义 props
导出方式: 使用 named export
路径别名: 利用 @/components/ui/*、@marketing/*、@dashboard/* 等别名

数据库操作

Schema 修改: 编辑 src/lib/database/prisma/schema.prisma
同步数据库: 运行 bun db:push
生成客户端: 运行 bun db:generate
查询函数: 在 src/lib/database/prisma/queries/ 下添加查询
类型安全: 使用 Prisma 生成的类型

API 路由开发

Hono 服务: 在 src/server/routes/ 下定义路由
Next.js API: 在 src/app/api/ 下创建路由处理器
验证: 使用 Zod 进行请求验证
认证: 集成 Better Auth 中间件
错误处理: 统一的错误响应格式
API 文档: 访问 http://localhost:3000/api/openapi

🔍 常用命令

# 开发
bun dev              # 启动开发服务器（使用 Turbo）
bun run build            # 构建项目
bun start            # 启动生产服务器
bun type-check       # TypeScript 类型检查

# 数据库 (Prisma)
bun db:push          # 同步数据库结构（开发环境）
bun db:migrate       # 创建和应用迁移（生产环境）
bun db:studio        # 打开 Prisma Studio 数据库管理界面
bun db:generate      # 重新生成 Prisma 客户端

# 代码质量 (Biome)
bun lint             # 代码检查和格式化检查
bun format           # 自动格式化代码

# UI 组件
bun shadcn-ui        # 添加 shadcn/ui 组件

# 测试
bun e2e              # 运行 Playwright E2E 测试（UI 模式）
bun e2e:ci           # 运行 E2E 测试（CI 模式）

🚨 常见问题解决

问题 1: `bun: command not found`

npm install -g bun

问题 2: 数据库连接失败

检查清单：

✅ 数据库 URL 格式正确
✅ 数据库服务正在运行
✅ 用户名密码正确
✅ 防火墙允许连接

问题 3: 端口 3000 被占用

# 使用其他端口
bun dev -- -p 3001

# 或者杀死占用端口的进程
lsof -ti:3000 | xargs kill -9

问题 4: TypeScript 类型错误

# 快速类型检查
bun type-check

# 重新生成 Prisma 类型
bun db:generate

# 清理 Next.js 缓存
rm -rf .next

问题 5: 环境变量不生效

✅ 检查 .env.local 文件是否在项目根目录
✅ 重启开发服务器
✅ 确保变量名前缀正确（客户端变量需要 NEXT_PUBLIC_）
✅ 检查变量名拼写是否正确

问题 6: Prisma 连接错误

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

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

# 重置数据库（谨慎使用）
bun db:push --force-reset

问题 7: 构建失败

# 清理缓存
rm -rf .next node_modules
bun install

# 检查类型错误
bun type-check

# 检查代码格式
bun lint

🎯 下一步学习路径

现在你已经了解了基础知识，建议按以下顺序深入学习：

🚀 快速上手路径

🔐 认证系统 - 配置 Better Auth，设置社交登录
🎨 UI 定制 - 定制主题和组件样式
🌐 国际化配置 - 添加新语言和本地化内容

💼 商业功能路径

💰 支付系统 - 集成 Stripe，设置订阅计划
👥 组织管理 - 支持团队协作和多租户
📊 分析统计 - 用户行为分析和业务指标

🤖 AI 功能路径

🤖 AI 功能 - 集成 OpenAI，构建 AI 聊天
📝 内容生成 - AI 辅助内容创作

📈 增长功能路径

📝 博客系统 - 内容营销和 SEO 优化
📧 邮件营销 - 用户触达和留存
🔗 API 开发 - 构建开放 API

🆘 获取帮助

💬 问 AI: 描述具体问题，如："我想添加用户资料编辑功能，怎么做？"
📖 查看源码: 代码有详细的 TypeScript 类型定义
🔍 搜索文档: 使用页面右上角的搜索功能

🎉 开始构建你的 AI 产品吧！ 这个仓库为你提供了所有必需的基础功能，让你专注于业务逻辑和用户价值。

快速入门指南

On this page