Claudable

无需复杂编码，只需用自然语言描述需求——比如“开发一个支持暗黑模式、数据同步的待办事项应用”，Claudable 就能借助 AI 力量自动生成生产级代码，实时预览可运行效果，还能一键部署到 Vercel 并接入数据库。这款基于 Next.js 的开源工具，完美融合了 Claude Code 等 AI 编码代理的强大能力与简洁直观的操作体验，让普通人也能轻松打造专业级网页应用。

核心优势：为什么选 Claudable？

• 零门槛上手：不用懂复杂技术，自然语言描述需求即可，AI 全程代写代码
• 全链路免费开源：工具本身无订阅费，支持免费部署，核心功能完全开源可自定义
• 即时反馈体验：AI 生成代码时实时热重载，改动即时可见，无需等待完整构建
• 开箱即用配置：内置 Tailwind CSS + shadcn/ui 美观 UI，无需额外折腾 API Key、沙盒环境
• 全平台覆盖：支持网页端使用，还提供 Mac、Windows、Linux 桌面客户端（Electron 构建）
• 生态无缝衔接：一键对接 Vercel 部署、GitHub 版本控制、Supabase 生产级数据库

支持的 AI 编码代理（按需选择）

Claudable 兼容多款主流 AI 编码工具，可根据自身需求和订阅情况挑选：

技术栈揭秘

Claudable 基于成熟技术栈构建，确保生成的应用稳定可靠：

• 前端框架：Next.js（高效构建 React 应用）
• UI 组件：Tailwind CSS + shadcn/ui（自动生成美观响应式界面）
• 数据库：Supabase（内置生产级 PostgreSQL 数据库 + 身份认证功能）
• 部署平台：Vercel（一键上线，无需额外配置）
• 版本控制：GitHub（自动关联仓库，支持持续部署）

前置要求（快速准备）

使用前需确保环境满足以下条件，几分钟即可配置完成：

1. Node.js 18 及以上版本
2. 已登录的 Claude Code / Cursor CLI 等支持的 AI 编码代理
3. Git 版本控制工具

快速开始：本地运行只需3步

# 1. 克隆仓库到本地
git clone https://github.com/opactorai/Claudable.git
cd Claudable

# 2. 安装依赖（建议使用 npm 避免兼容性问题）
npm install

# 3. 启动开发服务器
npm run dev

启动成功后，访问 http://localhost:3000 即可使用（端口被占用会自动切换，可查看 .env 文件确认实际端口）。

桌面版使用指南（Electron）

如果偏好桌面应用体验，可通过以下命令构建或运行：

# 开发模式（实时调试）
npm run dev:desktop

# 打包桌面应用（生成安装包）
npm run build:desktop

# 打包特定平台版本
npm run package:mac      # macOS 版本
npm run package:win      # Windows 版本
npm run package:linux    # Linux 版本

实用命令合集（避坑必备）

完整使用流程：从想法到上线

1. 打开 Claudable，连接已登录的 AI 编码代理（如 Claude Code）；
2. 在输入框用自然语言描述应用需求，例如：“我需要一个支持用户注册登录、分类管理、标签筛选的读书笔记应用，要有暗黑/浅色模式切换”；
3. AI 会自动生成项目结构、代码文件和配置，同时实时热重载预览界面，可随时修改需求让 AI 迭代优化；
4. 满意后通过内置集成功能，一键关联 GitHub 仓库（自动版本控制）；
5. 接入 Vercel 完成部署，生成可公开访问的在线链接；
6. 如需数据存储，配置 Supabase 数据库信息（Project URL + Anon Key + Service Role Key），即可实现数据持久化。

常见问题解决方案

1. 端口被占用

无需手动修改，程序会自动检测可用端口，查看项目根目录的 .env 文件即可获取实际访问地址。

2. 数据库迁移冲突（升级旧版本后报错）

通常是 Prisma 模型变更导致，执行 npm run prisma:reset 可解决，执行前务必用 npm run db:backup 备份数据，该命令会删除并重建本地数据库。

3. Windows/WSL 下 Claude Code 权限报错

错误提示：dangerously skip permissions cannot be used...
解决步骤：

1. 不要用 sudo 或 root 权限运行 Claudable；
2. 修正目录权限：

   sudo chown -R $(whoami):$(whoami) ~/Claudable
   

3. 重新安装 Claude Code（关闭 unsafe-perm）：

   npm install -g @anthropic-ai/claude-code --unsafe-perm=false
   

集成服务配置指南

GitHub 集成

1. 登录 GitHub，创建经典 Token（需至少包含 repo 权限）；
2. 打开 Claudable 设置 → 服务集成 → GitHub；
3. 输入 Token，系统会自动创建或关联仓库，实现代码自动提交和版本控制。

Vercel 部署

1. 登录 Vercel 账户，在账户设置中创建 Token；
2. 进入 Claudable 服务集成 → Vercel，输入 Token；
3. 点击“一键部署”，系统会自动创建 Vercel 项目并完成部署，生成在线访问链接。

Supabase 数据库配置

1. 登录 Supabase 控制台，创建新项目；
2. 进入项目仪表盘 → Settings → API；
3. 复制 Project URL、Anon Key（客户端公钥）、Service Role Key（服务端密钥）；
4. 在 Claudable 数据库设置中粘贴对应信息，即可接入生产级数据库和身份认证功能。

无论是快速原型验证、个人项目开发，还是小型团队协作，Claudable 都能大幅降低网页应用的构建门槛。