企业官网建设流程全解析

• 后端

PartyKit 是一个专注于简化多人（multiplayer）应用开发的开源工具链：你只需关注业务逻辑，就可以为自己的应用加入实时协作能力，而将实时基础设施的运维与水平扩展交给平台处理。本文基于 packages/partykit/README.md 展开，带你完成从创建项目、本地联调到云端部署的完整闭环，并深入 PartyKit 的服务端编程模型、partykit.json配置与 CLI 命令，最终掌握用几行代码写出可运行、可部署的实时应用的能力。

PartyKit 是什么：从“平台”到“一行代码”

官方 README 用一句话定义了 PartyKit 的定位：

PartyKit simplifies developing multiplayer applications. With PartyKit, you can focus on building multiplayer apps or adding real-time experiences to your existing projects with as little as one line of code. Meanwhile, PartyKit will handle operational complexity and real-time infrastructure scaling.

拆解这句话，核心价值有三点：

1. 降低实时开发门槛：为已有项目添加实时体验，最小改动可以只是一行客户端代码；
2. 服务端逻辑可编程：你可以用 TypeScript / JavaScript 编写完整的服务端业务逻辑，而不是只能使用平台预设的黑盒能力；
3. 运维与扩容交给平台：实时连接管理、实例调度、横向扩展等基础设施复杂度由 PartyKit 运行时承担。

从仓库文档 how-partykit-works.md 可以进一步确认底层机制：每个 PartyKit 服务端（称为Party）都由一个 Cloudflare Durable Object 支撑，运行在基于workerd的现代 JavaScript 运行时上；请求通过id路由，保证相同 id 一定落到同一个 room（Party 实例），新 id 则按需创建新实例。因此每个 Party 既是“按需”的（类似 Serverless 函数、近乎零启动开销），又是“有状态”的（可以像普通类一样维护内存状态）。所有 Party 都运行在 Cloudflare 全球边缘网络，适合对延迟敏感的实时场景。

“一行代码”的体验来自官方客户端 SDKPartySocket，例如：

import PartySocket from "partysocket"; const socket = new PartySocket({ host: window.location.host, // 本地开发时即 localhost:1999 room: "my-room" });

从 packages/partysocket/README.md 可以看到，PartySocket 是一个与 WebSocket API 兼容、支持断线自动重连、离线消息缓冲、连接超时处理的多平台客户端，它既可用于 PartyKit，也可以独立对接任何 WebSocket 服务。

环境准备：Node.js 17+

运行 PartyKit 的前置条件只有一个：Node.js v17 或更高版本（README 明确标注）。建议使用当前主流的 LTS 版本，后续所有命令均在满足该条件的终端中执行。

快速开始一：创建全新 PartyKit 项目

在终端执行：

npm create partykit@latest

该命令会启动交互式向导，询问若干关于项目的问题（项目目录名、使用的模板、是否安装依赖等），然后在当前目录下创建一个全新的 PartyKit 应用目录，其中同时包含服务端（server）与客户端（client），开箱即跑。

模板选择

从脚手架实现 packages/create-partykit/src/index.tsx 可以看到，create-partykit内置了以下模板：

CLI 标志：跳过交互、加速创建

脚手架默认以交互模式运行，但也支持通过命令行参数直接指定选项（详见 packages/create-partykit/README.md）：

例如，一键生成一个 TypeScript 项目并跳过所有提问：

npm create partykit@latest -- --yes

快速开始二：将 PartyKit 接入现有项目

如果要把 PartyKit 加入一个已有的 npm 项目，在项目根目录执行：

npx partykit@latest init

从 CLI 实现 packages/partykit/src/cli.tsx 可以还原init的完整行为：

1. 检测项目环境：向上查找package.json（判断是否已在项目内）、.git（判断是否 git 仓库）、tsconfig.json（判断是否为 TypeScript 项目），并识别当前使用的包管理器（npm / yarn / pnpm）；
2. 安装依赖：自动安装最新版partykit与partysocket（版本从 npm registry 实时拉取，拉取失败时回退为*），其中partykit会写入项目的开发依赖；
3. 生成脚手架文件：创建partykit.json配置文件，以及可作起点的server.ts与client.ts示例；
4. 项目命名：默认采用package.json中的name字段作为 PartyKit 项目名。

如果你更喜欢 JavaScript，init 也提供了对应的 JS 版本服务端模板，见 packages/partykit/init/index.js——它基于@typedef的 JSDoc 类型标注实现了与 TS 模板完全一致的Party.Server类。

本地开发：启动 dev server

进入项目目录后，执行 README 推荐的：

npm run dev

它底层对应npx partykit dev。dev 命令会：

• 监听代码变更并自动重启：修改server.ts等源码后无需手动重启；
• 以partykit.json的main字段为入口：也可以显式指定入口，如npx partykit dev src/server.ts；
• 默认监听 1999 端口：该默认值在 packages/partykit/src/dev.tsx 的getPortForServer("dev", 1999)中有源码依据；若partykit.json配置了port字段则优先使用配置值。

启动后在浏览器分别打开两个窗口访问http://localhost:1999，即可模拟两个用户同时使用你的应用，实时观察连接建立与消息广播的效果。

客户端连接：PartySocket 实战

以仓库内置示例 examples/basic/src/client.ts 为蓝本，一个典型的 PartyKit 客户端长这样：

import PartySocket from "partysocket"; const partySocket = new PartySocket({ host: window.location.host, // 本地开发指向 localhost:1999 room: "some-room" }); partySocket.onopen = () => partySocket.send("ping"); partySocket.onmessage = (evt) => { console.log("received:", evt.data); };

要点说明：

• room：要加入的房间 id，同一个房间内的所有客户端共享同一个服务端实例；
• host：window.location.host可同时适配本地开发（localhost:1999）与云端部署（<name>.<user>.partykit.dev）两种环境；
• 重连与缓冲：PartySocket 在连接断开后自动重连，未连接期间发送的消息会排队缓冲，连接恢复后自动补发（详见 packages/partysocket/README.md）。

如果项目使用 React，还可以直接使用partysocket/react提供的usePartySocketHook，见 examples/react/src/client.tsx：

import usePartySocket from "partysocket/react"; function App() { const socket = usePartySocket({ room: "test", onOpen() { socket.send("ping"); }, onMessage(message) { console.log("received", message.data); } }); return <div>hello world</div>; }

部署上线：一键发布到 PartyKit 云

开发调试完成后，执行：

npm run deploy

即npx partykit deploy。部署流程的关键点（参见 deploying-your-partykit-server.md 与 partykit-cli.md）：

1. 首次部署需登录：浏览器会打开 GitHub 授权页，完成授权后即登录 PartyKit 服务（后续可用npx partykit login手动登录，npx partykit logout登出，npx partykit whoami查看当前用户）；
2. 获取公网域名：部署完成后，应用会获得形如[项目名].[GitHub用户名].partykit.dev的域名，域名签发最长需要两分钟；
3. 入口与命名：默认读取partykit.json中的main（入口）与name（项目名），也可以命令行覆盖：npx partykit deploy src/server.ts --name my-project。

部署后的运维命令

环境变量管理

env子命令族用于管理部署到平台的环境变量（详细指南见 managing-environment-variables.md）：

• npx partykit env list：列出项目已配置的所有环境变量 key；
• npx partykit env add <key>：创建或更新环境变量（会交互式提示输入值），新增变量需重新deploy才生效；
• npx partykit env remove <key>：删除环境变量（旧值在下次 deploy 前仍可用）；
• npx partykit env pull [filename]：把全部环境变量写入 JSON 文件（不传文件名则回写到partykit.json）；
• npx partykit env push：把partykit.json中配置的环境变量推送到平台；
• 单次部署级变量：npx partykit deploy --var API_KEY=$API_KEY，或在.env文件中定义后执行npx partykit deploy --with-vars。

另外，npx partykit token generate可以生成 OAuth token，供 GitHub Actions 等 CI 环境代表你执行部署（参见 setting-up-ci-cd-with-github-actions.md）。

服务端编程模型：Party.Server 与 Room

init 生成的服务端模板（packages/partykit/init/index.ts）展示了一个完整可用的聊天服务端：

import type * as Party from "partykit/server"; export default class Server implements Party.Server { constructor(readonly room: Party.Room) {} onConnect(conn: Party.Connection, ctx: Party.ConnectionContext) { // 新 WebSocket 连接建立 console.log(`Connected: ${conn.id} in room ${this.room.id}`); conn.send("hello from server"); } onMessage(message: string, sender: Party.Connection) { // 收到消息后广播给房间内其他所有连接（排除发送者自己） this.room.broadcast(`${sender.id}: ${message}`, [sender.id]); } } Server satisfies Party.Worker;

从 packages/partykit/src/server.ts 的类型定义可以梳理出服务端 API 的全貌：

• Party.Server：核心生命周期接口，提供onStart（首次启动/唤醒时加载数据）、onConnect（连接建立）、onMessage（收到消息）、onClose（连接关闭）、onError（连接异常）、onRequest（HTTP 请求）、onAlarm（定时告警）等钩子；options.hibernate可控制实例在请求/消息间隔是否从内存卸载，以提升单实例可承载的连接数；
• Party.Room：每个 Party 实例的上下文，包含id、name、env（环境变量）、storage（per-party 的键值存储）、broadcast()、getConnections()、context.parties（访问同项目内其他 Party）等；
• Party.Connection：一条 WebSocket 连接的抽象，除标准 WebSocket 能力外还附带id、state（连接级任意状态，通过setState更新）与setState；
• Party.Worker：用于自定义边缘层路由行为，支持onFetch、onSocket、onBeforeRequest、onBeforeConnect、onCron等静态钩子。

在运行时层面（见 packages/partykit/facade/worker.ts），框架提供了两种服务端适配器：ClassWorker适配类式Party.Server写法，ModuleWorker则兼容早期export default {} satisfies PartyKitServer的模块式写法（该写法现已标记为 legacy，新项目官方推荐类式 API）。需要特别留意的是，模块式服务端在定义了onMessage或未定义onConnect时会被视为支持休眠（hibernation）模式。

partykit.json 配置速查

partykit.json是项目的核心配置文件，完整字段约束定义在 packages/partykit/schema.json（JSON Schema，可直接获得编辑器补全与校验），详细说明见 partykit-configuration.md。以下为最常用的字段：

仓库示例 examples/basic/partykit.json 综合展示了上述多数字段的用法（多 Party、define、serve静态托管、vars等）。由于partykit.json受 JSON Schema 约束（additionalProperties: false），任何未收录的字段都会在配置加载时被拒绝，这也保证了配置的确定性。

下一步学习路径

围绕本文提到的核心能力，仓库内还提供了大量可直接查阅的资源：

• 完整文档与更多指南：见 apps/docs 目录，包括 quickstart.md、partykit-cli.md、partyserver-api.md；
• 可运行示例：见 examples 目录，覆盖 basic、react、yjs、persistence、ai 等场景；
• 服务端 API 完整类型定义：packages/partykit/src/server.ts；
• CLI 源码（init / dev / deploy / tail 等命令实现）：packages/partykit/src/cli.tsx；
• 客户端 SDK 与 React Hook：packages/partysocket/README.md；
• 官方博客与发布说明：见 apps/blog。

从npm create partykit@latest到npm run deploy，整个“开发—联调—上线”闭环只需几个命令即可走通；而当你需要深入定制时，Party.Server的完整生命周期钩子、partykit.json的丰富配置项以及可编程的服务端运行时，又为任意复杂的实时业务场景保留了充分的发挥空间。

• 后端