serverpod-overview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Serverpod Overview

Serverpod 概述

Serverpod is an open-source backend framework for Flutter written in Dart. A Serverpod project consists of usually three packages:

my_project_server

- the server code.

my_project_client

- generated client code.

my_project_flutter

- a Flutter app (imports the client).

There can also be packages that share code, e.g.,

my_project_shared

The server starts in

lib/server.dart

, which creates the generated

Serverpod

class from

src/generated/serverpod.dart

(pre-wired with the project's protocol and endpoints) with

final pod = Serverpod(args);

and then

await pod.start();

The server exposes endpoint classes that the client calls via generated RPC client. Add methods to the endpoints, the code generation will recreate them on the client side. Models are defined in YAML and generate Dart classes for both server and client.

Serverpod projects use a PostgreSQL database for persistence (SQLite is also supported) and include an ORM, caching, real-time streaming (using Dart streams), file uploads, scheduling (called future calls), logging, and a built-in web server (Relic).

Each of these feature areas has its own

serverpod-*

skill; use the one that matches the task. The Insights companion app is not covered by a skill and is documented at https://docs.serverpod.dev.

Serverpod 是一个用于 Flutter 的开源后端框架，使用 Dart 编写。一个 Serverpod 项目通常包含三个包：

my_project_server

- 服务器代码。

my_project_client

- 生成的客户端代码。

my_project_flutter

- Flutter 应用（导入客户端代码）。

也可以存在共享代码的包，例如

my_project_shared

。

服务器从

lib/server.dart

启动，通过

final pod = Serverpod(args);

创建从

src/generated/serverpod.dart

生成的

Serverpod

类（已预先配置项目的协议和端点），然后调用

await pod.start();

。

服务器暴露端点类，客户端通过生成的 RPC 客户端调用这些类。在端点中添加方法，代码生成工具会在客户端侧重新创建这些方法。模型通过 YAML 定义，并为服务器和客户端生成 Dart 类。

Serverpod 项目使用 PostgreSQL 数据库进行持久化（也支持 SQLite），并包含 ORM、缓存、实时流（使用 Dart streams）、文件上传、调度（称为 future calls）、日志记录以及内置 Web 服务器（Relic）。

每个功能领域都有对应的

serverpod-*

技能；请使用与任务匹配的技能。Insights 配套应用没有对应的技能，其文档可访问 https://docs.serverpod.dev。

Running the server

运行服务器

The user runs the server with

serverpod start

, which watches for file changes to run incremental code generation and hot reload the server (and the Flutter app, when the project has one).

Do not check whether the server is running before acting: make the changes and call the

serverpod

MCP tools. When nothing is running, the MCP answers with an explicit "the server is not running" error. Only then, stop and ask the user to start it. NEVER start the server yourself.

ALWAYS use the MCP server instead of the command line. A running

serverpod start

exposes:

```
create_migration
```
and
```
apply_migrations
```
for the database (after you change data models).
```
create_repair_migration
```
when the database has drifted out of sync with the migrations. It only writes the repair file; follow up with
```
apply_migrations
```
.
```
tail_server_logs
```
to read logs from the server.
```
tail_flutter_logs
```
to read raw stdout/stderr from a Flutter app.
```
hot_reload
```
to reload the server and the Flutter app while keeping in-memory state. Only needed with
```
--no-watch
```
, since
```
serverpod start
```
reloads on file changes.
```
hot_restart
```
to restart the server and the Flutter app, dropping in-memory state. ALWAYS call it after doing changes in the Flutter app that may not work with normal hot reload (which is automatically applied).

spawn_flutter_app

to start a Flutter app declared under

serverpod: flutter_apps:

in the server

pubspec.yaml

```
get_flutter_app_dtd
```
to get the Dart Tooling Daemon URI of a running Flutter app. Pass it to the
```
dart
```
MCP to drive the app.

Tools that target a Flutter app take an optional

appId

, which is the map key under

serverpod: flutter_apps:

. It is required only when the project declares more than one app.

用户使用

serverpod start

命令运行服务器，该命令会监听文件变化以运行增量代码生成并热重载服务器（如果项目包含 Flutter 应用，也会热重载该应用）。

在操作前无需检查服务器是否正在运行：直接进行更改并调用

serverpod

MCP 工具。如果没有服务器在运行，MCP 会返回明确的“服务器未运行”错误。只有此时，才停止操作并要求用户启动服务器。切勿自行启动服务器。

务必使用 MCP 服务器而非命令行。运行

serverpod start

后会提供以下功能：

```
create_migration
```
和
```
apply_migrations
```
：用于数据库操作（在更改数据模型后）。
```
create_repair_migration
```
：当数据库与迁移不同步时使用。它仅生成修复文件，后续需调用
```
apply_migrations
```
。
```
tail_server_logs
```
：读取服务器日志。
```
tail_flutter_logs
```
：读取 Flutter 应用的原始标准输出/标准错误。
```
hot_reload
```
：重新加载服务器和 Flutter 应用，同时保留内存状态。仅在使用
```
--no-watch
```
时需要，因为
```
serverpod start
```
会在文件变化时自动重载。
```
hot_restart
```
：重启服务器和 Flutter 应用，清除内存状态。在对 Flutter 应用进行可能无法通过常规热重载生效的更改后，务必调用此命令（常规热重载会自动应用）。

spawn_flutter_app

：启动服务器

pubspec.yaml

中

serverpod: flutter_apps:

下声明的 Flutter 应用。

```
get_flutter_app_dtd
```
：获取运行中 Flutter 应用的 Dart Tooling Daemon URI。将其传递给
```
dart
```
MCP 以驱动应用。

针对 Flutter 应用的工具可选择传入

appId

，即

serverpod: flutter_apps:

下的映射键。仅当项目声明了多个应用时才需要传入。

Working on the project with no running instance

无运行实例时处理项目

NEVER use the CLI unless you have already attempted to use the MCP.
ONLY if you cannot connect to the MCP server, the code can be generated by calling
```
serverpod generate
```
.
NEVER edit the generated code, as it will be overwritten by the next generation. This does not cover the SQL of a created migration, which may be edited — see the Serverpod Migrations skill.

After generating the code, database migrations can be created by calling

serverpod create-migration

. Use ONLY if you cannot use the MCP.

bash

undefined

除非已尝试使用 MCP，否则切勿使用 CLI。
仅当无法连接到 MCP 服务器时，才可通过调用
```
serverpod generate
```
生成代码。
切勿编辑生成的代码，因为下次生成时会被覆盖。但创建的迁移文件中的 SQL 可以编辑——请参阅 Serverpod 迁移技能。

生成代码后，可通过调用

serverpod create-migration

创建数据库迁移。仅当无法使用 MCP 时才使用此方法。

bash

undefined

Use

--force

to create migrations with destructive changes

使用

--force

创建包含破坏性更改的迁移

Use the

--tag

flag to name the migration

使用

--tag

标记为迁移命名

serverpod create-migration [--force] [--tag <tag>]


See the [Serverpod Migrations](../serverpod-migrations/SKILL.md) skill for more details.

Checklist after doing changes:

1. `dart analyze` (CLI, or the `dart` MCP server)
2. `dart format` (CLI, or the `dart` MCP server)
3. Do `serverpod` MCP `hot_restart` if required (hot reload is done automatically). Will also hot restart Flutter app
4. Check `serverpod` MCP `tail_server_logs` (and `tail_flutter_logs` for a Flutter app) for any issues