企业官网建设流程全解析

Vibe Kanban 如何为仓库配置 Setup 脚本，让代理启动前自动安装依赖并准备环境

【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban

在 Vibe Kanban 中，每次代理执行任务都会运行在一个新建的 git worktree 里，这个隔离环境里通常不包含你本地仓库的依赖、.env和配置文件。如果什么都不配，代理需要自己摸索“还没装依赖”这件事，既慢又不可靠。Vibe Kanban 提供了 Setup 脚本：在仓库级别配置一组命令，代理启动前自动在仓库根目录执行，用于安装依赖、准备构建产物或初始化环境。本文说明如何为仓库配置 Setup 脚本、配置后如何验证它确实运行了，以及脚本失败时按文档排查的顺序。

为什么需要 Setup 脚本

文档给出的使用动机有三个（见 Projects & Repositories）：

• 安装依赖：确保所有包在代理改代码之前已经装好；
• 构建前置产物：编译共享库或生成代理需要的文件；
• 环境准备：初始化数据库、拉取 Docker 镜像、配置服务。

Creating Projects 进一步解释了必要性：每次代理执行都在 git worktree 中运行，而 worktree 里“不太可能”包含你的依赖、配置和.env。用 Setup 脚本（例如npm install或cargo build）提前跑一遍，代理就不需要自己发现这些命令没执行过。

配置入口：Settings 中的 Repositories 标签页

按 Projects & Repositories 的说明操作：

1. 从 Workspaces 导航栏打开Settings；
2. 选择Repositories标签页；
3. 从下拉框中选择要配置的仓库。

该页面除了Display Name（仓库显示名）和Repository Path（仓库本地路径）外，还有 Scripts & Configuration 区域，用来配置这个仓库的 dev server、setup、cleanup 三类脚本。这些脚本在该仓库被任何 workspace 使用时都会生效。创建项目后也可以通过项目卡片右上角的设置按钮进入同样的项目级脚本配置（见 Creating Projects）。

填写 Setup 脚本

在 Setup Script 一栏填入代理启动前要执行的命令。Setup 脚本的语义是：在编码代理开始工作之前运行，用于准备开发环境。文档给出的示例（按语言/包管理器选择其一即可）：

# Node.js 项目 npm install # Python 项目 pip install -r requirements.txt # 多条命令用 && 串联 npm install && npm run build:deps # Rust 项目 cargo fetch

如果仓库需要本地环境文件，可以在同一设置页配置Copy Files：一个逗号分隔的文件列表，从原项目目录复制到 worktree。文档说明这些文件在 worktree 创建之后、Setup 脚本运行之前被复制，适合.env、配置文件和本地设置这类环境相关文件。注意文档的警告：这些文件必须被 gitignore，否则可能被提交进代码库。

配置前先在终端里手动跑一遍脚本。Projects & Repositories 的最佳实践明确要求：在 Vibe Kanban 里配置之前，先手动运行脚本确认它能正常工作。

执行时机：工作区创建时自动运行

配置完成后不需要手动触发。按 Creating Workspaces 的描述，创建工作区时会依次发生：

1. 创建 git worktree（独立工作目录和分支，原仓库不受影响）；
2. 基于目标分支（如main）自动创建工作分支；
3. 初始化编码代理会话；
4. 如果仓库配置了 Setup 脚本，自动运行以准备环境。

Monitoring Task Execution 描述的任务执行顺序与此一致：Git worktree 创建 → Setup 脚本运行 → 代理开始处理任务。Setup 脚本在仓库根目录执行；Projects & Repositories 特别指出，它在 workspace 启动时执行一次，而不是每条代理消息都执行。

工作区创建流程（点+按钮或Cmd/Ctrl + K选New Workspace）本身不涉及脚本配置，选中配好 Setup 脚本的仓库后，脚本会在启动时自动跑完，代理才开始干活。

验证脚本确实运行了

文档提供了三种检查方式：

• 看日志：Monitoring Task Execution 说明，任务开始后你看到的第一条日志就是 Setup 脚本在运行（如果配置了的话），它安装依赖、准备环境，然后代理才开始工作。日志里能看到脚本执行的实时输出。
• 手动重跑：Workspaces 界面提供R S组合键直接执行 Setup 脚本（R C执行 cleanup 脚本，见 Keyboard Shortcuts）。在 workspace 里按R S可以单独重跑一次脚本来确认行为。
• View Processes：点界面右上角的三点图标选View Processes，可以看到运行中和已完成的进程及各自的输出日志，包括构建类脚本。

如果用的是 Web 应用，Testing Your Application 提醒：配置 dev server 脚本前，通常也需要配置 Setup 脚本（如npm install），否则开发服务器启动时缺少依赖，这个配置同样放在项目设置的 Setup Scripts 中。

脚本失败时按文档排查

Creating Workspaces 的故障排查部分列出了 Setup 脚本失败的三类可能原因和对应处理：

同时查看Logs 面板里的错误信息定位具体失败位置。这与脚本配置页的最佳实践呼应：脚本从仓库根目录运行，应使用相对路径或环境变量，不要写死绝对路径。

写脚本时的三条建议同样来自 Projects & Repositories：

• 保持脚本快速：耗时过长的 Setup 会拖慢 workspace 启动，依赖安装可以放这里，但冗长的构建过程能免则免；
• 优雅处理错误：可能失败但不该阻塞 workspace 的命令，加上|| true，例如npm install || true；
• 用相对路径：脚本从仓库根目录运行。

边界与说明

• Setup 脚本按仓库配置，在该仓库被任何 workspace 使用时生效；项目设置在其适用范围内会覆盖全局设置。
• 脚本在 worktree 的仓库根目录执行一次，不在每条消息时重复执行；需要每轮代理结束后做的事（格式化、清理）应配在 Cleanup 脚本里，而不是塞进 Setup 脚本。
• 除 UI 配置外，Vibe Kanban 的 MCP Server 也提供update_setup_script工具，传入repo_id和script即可更新某仓库的 Setup 脚本（见 Vibe Kanban MCP Server），适合在终端代理里顺带管理仓库脚本。

配置完成后，新建一个使用该仓库的工作区，在 Logs 面板确认第一条日志就是 Setup 脚本输出且无报错、代理随后正常开始处理任务，即表示配置生效。

【免费下载链接】vibe-kanbanGet 10X more out of Claude Code, Codex or any coding agent项目地址: https://gitcode.com/GitHub_Trending/vi/vibe-kanban