start-dev-server

步骤 0：了解用户偏好

• 询问用户是否希望在当前会话中将开发服务器作为后台任务启动，还是在单独的终端中自行启动：
  • 作为后台任务启动
    • 优点：Agent 拥有更高的自主性，可以直接响应开发服务器日志（警告、错误）。
    • 缺点：某些操作可能会变慢，而且用户的直接控制权较少。用户只能在 background tasks 选项卡中查看服务器日志。
  • 外部启动（用户自行启动）
    • 优点：用户可以更直接地控制应用开发和 Wasp CLI 命令。对更高级的用户来说，这可能更有优势。
    • 缺点：调试和发现功能可能会更慢，因为 Agent 无法直接访问开发服务器日志（警告、错误）或 Wasp CLI 命令。
• 根据用户的选择，按照以下步骤执行，并在后台为用户运行命令，或指导用户在单独的终端中手动运行命令。

步骤 1：准备检出代码

如果缺少 node_modules，请安装项目依赖项：

wasp install

如果缺少 .env.server 或 .env.client，且有 .env.server.example 或 .env.client.example，请根据示例文件创建缺少的文件。请用户编辑文件并设置正确的值。

步骤 2：确保开发数据库正在运行

在 .env.server 文件中搜索 DATABASE_URL。如果没有任何行以 DATABASE_URL 开头，请继续执行此步骤。 如果用户已设置自己的 DATABASE_URL 环境变量，请转到步骤 3。

检查项目根目录中的 schema.prisma 文件，查看正在使用的数据库类型。

SQLite

跳转至步骤 3： SQLite 会将数据存储在本地文件中，无需数据库服务器。

PostgreSQL

将托管数据库容器作为后台任务启动：

wasp start db

要运行托管的 Postgres 数据库容器（wasp start db），必须安装并运行 Docker。

在当前会话中将其作为后台任务运行。 等待 5-15 秒，让数据库准备就绪。

步骤 3：运行数据库迁移

如果这是首次启动应用，或存在待处理的迁移，请运行以下命令：

wasp db migrate-dev --name <migration-name>

某些应用需要种子数据才能正常工作。运行以下命令以填充数据库：

wasp db seed <name>

步骤 4：启动开发服务器

将 Wasp 开发服务器作为后台任务启动：

wasp start

步骤 5：验证服务器是否正在运行

从 wasp start 输出中读取客户端和服务器 URL，并验证客户端能否加载。

在 Wasp 0.26+ 中，验证服务器在 /up 返回 HTTP 200。被占用的端口会自动替换。使用 --client-port 和 --server-port 选择端口，或使用 --client-url 和 --server-url 设置可从外部访问的 URL。URL 覆盖参数不会选择监听端口。开发端口和 URL 由 Wasp 管理，因此请从 .env.server 中移除 PORT、WASP_SERVER_URL 和 WASP_WEB_CLIENT_URL，从 .env.client 中移除 REACT_APP_API_URL，并从 Vite 配置中移除 server.port/server.strictPort。部署环境变量保持不变。

在 Wasp 0.26+ 中，托管数据库也会选择一个空闲端口。Wasp 会自动发现该端口。需要固定数据库端口时，请使用 wasp start db --db-port <port>。

如果在当前会话中作为后台任务启动： 关注输出中的开发和调试信息。 如果在外部启动： 请告知用户查看外部终端的输出，并将输出分享给你。

第 6 步：连接浏览器控制台（重要！）

这一步对于高效开发和调试至关重要。 如果无法访问浏览器控制台，Agent 就无法查看浏览器中出现的客户端错误、警告或 React 问题。

通过 AskUserQuestion 工具询问用户希望使用哪种方式，让 Agent 能够查看浏览器控制台：

选项	说明
Chrome DevTools MCP（推荐）	必须先安装
内置 Chrome	使用 Claude Code 内置的浏览器连接（使用 /chrome 命令检查状态）
手动	需要时由用户手动复制/粘贴控制台输出
其他	用户有其他偏好

如果选择 Chrome DevTools MCP，但尚未安装，请将以下配置添加到其 MCP 客户端：

{
  "mcpServers": {
    "chrome-devtools": {
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"]
    }
  }
}