环境搭建指南
按步骤配置本地开发环境。
前置要求
验证环境
bash
node --version # 应显示 v18.0.0 或更高
pnpm --version # 应显示 8.0.0 或更高
git --version # 应显示 git version 2.x.x克隆项目
bash
git clone https://github.com/sherlocknieh/TodoHeap.git
cd TodoHeap安装依赖
bash
# 使用 pnpm workspace 安装所有依赖
pnpm install
# 如果遇到问题，尝试清除缓存后重新安装
pnpm store prune
pnpm install启动前端开发服务器
bash
cd frontend
pnpm dev访问 http://localhost:5173，应该看到 TodoHeap 应用的登录页面。
常见问题
端口已被占用？
bash
pnpm dev -- --port 3000 # 使用其他端口无法访问本地服务？
- 检查防火墙是否阻止
- 尝试访问 http://127.0.0.1:5173 替代 localhost
配置 Supabase（本地数据库开发）
前置条件
- 已安装 Supabase CLI
- 已安装 Docker（Supabase 本地服务需要）
初始化 Supabase
bash
# 在项目根目录
supabase init
# 启动本地 Supabase 服务（PostgreSQL + API）
supabase start
# 输出示例：
# Started supabase local development setup.
# API URL: http://localhost:54321
# DB URL: postgresql://postgres:postgres@localhost:54321/postgres
# Anon Key: eyJ...应用迁移
第一次启动时，Supabase 会自动应用所有迁移脚本。
验证数据库：
bash
# 进入 psql 交互式 shell
supabase db push
# 或使用 psql 直接连接
psql postgresql://postgres:postgres@localhost:54321/postgres查看 Supabase Studio（管理界面）
启动后访问 http://localhost:54323，可视化管理数据库。
停止 Supabase
bash
supabase stop重置数据库
bash
# 删除所有数据，重新应用迁移
supabase db reset
# 或完全重置本地环境
supabase stop --remove-volumes
supabase start环境变量配置
前端环境变量
在 frontend/ 创建 .env.local（仅本地开发使用）：
bash
# Supabase 本地配置（开发环境）
VITE_SUPABASE_URL=http://localhost:54321
VITE_SUPABASE_ANON_KEY=your_anon_key_here
# 或使用生产 Supabase 项目（需注册）
# VITE_SUPABASE_URL=https://your-project.supabase.co
# VITE_SUPABASE_ANON_KEY=your_anon_key获取本地密钥：
bash
# Supabase 启动时会输出，或查看：
supabase status后端环境变量
Edge Functions 的环境变量在 supabase/config.toml 中配置：
toml
[env.local]
# AI 大模型 API 配置
AI_API_KEY = "your_api_key_here"
AI_API_URL = "https://api.example.com"本地开发工作流
完整启动顺序
bash
# 1. 启动 Supabase（后端）
supabase start
# 2. 在新终端启动前端（在 frontend/ 目录）
cd frontend
pnpm dev
# 3. 打开浏览器访问
# http://localhost:5173常用命令
bash
# 查看 Supabase 状态
supabase status
# 查看 Supabase 日志
supabase logs --local
# Edge Functions 开发模式（监听源码变化自动重新加载）
supabase functions serve --no-verify-jwt
# 查看本地前端日志
cd frontend && pnpm dev
# 运行前端单元测试
cd frontend && pnpm test
# 类型检查
cd frontend && pnpm type-check
# 代码格式化
pnpm format项目结构快速定位
TodoHeap/
├── frontend/ # Vue 3 前端应用
│ ├── src/
│ │ ├── components/ # UI 组件
│ │ ├── pages/ # 页面
│ │ ├── stores/ # Pinia 状态管理
│ │ ├── lib/supabase.ts # Supabase 初始化
│ │ └── style.css # 全局样式
│ ├── vite.config.ts # Vite 配置
│ ├── tailwind.config.js # Tailwind 配置
│ └── package.json
│
├── supabase/
│ ├── functions/ # Edge Functions (Deno)
│ │ ├── breakdown_task/ # 任务分解
│ │ ├── analyze_task_create/# 任务分析
│ │ └── optimize_tasks/ # 任务优化
│ │
│ ├── migrations/ # 数据库迁移脚本
│ │ ├── 20251212040000_create_todos_table.sql
│ │ └── ...其他迁移
│ │
│ ├── config.toml # Supabase 配置
│ └── seed.sql # 数据库初始化数据（可选）
│
└── docs/ # 文档
└── zh/dev/ # 开发文档编辑器配置
VS Code 推荐扩展
json
// 在 .vscode/extensions.json 中
{
"recommendations": [
"Vue.volar", // Vue 3 语言支持
"esbenp.prettier-vscode", // 代码格式化
"dbaeumer.vscode-eslint", // ESLint
"bradlc.vscode-tailwindcss", // Tailwind CSS
"denoland.vscode-deno", // Deno 支持（Edge Functions）
"github.copilot" // GitHub Copilot
]
}安装：打开 VS Code 扩展商店，搜索上述扩展安装。
故障排除
问题：pnpm install 失败
bash
# 清除缓存
pnpm store prune
# 删除 node_modules 和 lock 文件
rm -rf node_modules pnpm-lock.yaml
# 重新安装
pnpm install问题：前端无法连接 Supabase
检查 .env.local 中的 URL 和 Key 是否正确：
bash
supabase status # 查看本地 API URL 和 anon key问题：Edge Functions 调用失败
bash
# 查看 Edge Functions 日志
supabase logs --local
# 确保 functions 已部署
supabase functions serve --no-verify-jwt问题：数据库连接错误
bash
# 重置数据库
supabase db reset
# 检查迁移脚本
supabase migration list
# 手动应用迁移
supabase db push下一步
环境搭建完成后：