主题
安装配置
本文档详细说明 Vibe Kanban 的安装要求和环境配置。
系统要求
运行时要求
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 18.x | 20.x LTS |
| pnpm | 8.x | 最新稳定版 |
开发环境要求
如果您需要从源码构建或参与开发，还需要：
| 组件 | 版本要求 |
|---|---|
| Rust | 最新稳定版 |
| cargo-watch | 最新版 |
| sqlx-cli | 最新版 |
安装方式
方式一：npx 直接运行（推荐）
无需安装，直接运行：
bash
npx vibe-kanban方式二：全局安装
bash
# 使用 npm
npm install -g vibe-kanban
# 使用 pnpm
pnpm add -g vibe-kanban
# 安装后运行
vibe-kanban方式三：从源码构建
bash
# 克隆仓库
git clone https://github.com/BloopAI/vibe-kanban.git
cd vibe-kanban
# 安装依赖
pnpm install
# 构建前端
cd frontend && pnpm build && cd ..
# 启动开发服务器
pnpm run dev环境变量配置
Vibe Kanban 支持通过环境变量进行配置。
运行时环境变量
| 变量名 | 说明 | 默认值 |
|---|---|---|
HOST | 后端服务器主机地址 | 127.0.0.1 |
PORT | 后端服务器端口 | 3000 |
VK_ALLOWED_ORIGINS | 允许的跨域来源（CORS） | - |
MCP_HOST | MCP 服务主机地址 | 127.0.0.1 |
MCP_PORT | MCP 服务端口 | 8080 |
构建时环境变量
| 变量名 | 说明 |
|---|---|
POSTHOG_API_KEY | PostHog 分析服务 API Key |
反向代理配置
如果您在反向代理或自定义域名后部署 Vibe Kanban，必须设置 VK_ALLOWED_ORIGINS 环境变量，否则会因来源不匹配导致 403 错误。
bash
# 设置允许的来源
export VK_ALLOWED_ORIGINS="https://your-domain.com"
# 启动服务
vibe-kanban支持多个来源（逗号分隔）：
bash
export VK_ALLOWED_ORIGINS="https://app.example.com,https://dev.example.com"验证安装
安装完成后，运行以下命令验证：
bash
# 启动 Vibe Kanban
npx vibe-kanban
# 或使用全局安装的命令
vibe-kanban成功启动后，在浏览器中访问显示的地址（默认为 http://127.0.0.1:3000）。
常见问题
Node.js 版本不满足要求
如果您的 Node.js 版本低于 18，请使用 nvm 或 n 升级：
bash
# 使用 nvm
nvm install 20
nvm use 20
# 使用 n
n ltspnpm 未安装
bash
# 使用 npm 安装 pnpm
npm install -g pnpm
# 或使用 corepack（Node.js 16.13+）
corepack enable
corepack prepare pnpm@latest --activate