企业官网建设流程全解析

• 后端

本文基于 PartyKit 官方部署指南展开，完整讲解如何将 PartyKit 多人在线应用部署到云端：包括首次部署的登录授权流程与partykit.dev域名分配规则、部署时注入环境变量的两种方式、用tail命令实时排查线上问题，以及通过 GitHub Actions 实现"提交即部署"的完整 CI/CD 流水线。读完本文，你将掌握一套从本地开发到生产上线、再到线上调试与自动化发布的完整实战流程。

一、部署前的准备：登录与授权

PartyKit 的部署命令会读取项目根目录下的partykit.json配置文件（包括name与main两个关键字段），将本地代码上传到云端运行。在首次执行部署命令前，CLI 会自动触发登录流程。

根据 deploying-your-partykit-server.md 的说明，首次运行时你会被引导使用 GitHub 登录，浏览器会打开一个设备激活页面（device activation page），授权后 CLI 即可代表你进行部署。

从源码结构看，当前版本（config.ts）支持两种登录方式：github与clerk（PartyKit 自有账号体系），登录凭据会持久化写入~/.partykit/config.json。因此你也可以主动执行npx partykit login提前完成认证，避免在部署时被中断。此外，getUserConfig 表明 CLI 还支持通过环境变量PARTYKIT_LOGIN+PARTYKIT_TOKEN（或GITHUB_LOGIN+GITHUB_TOKEN）直接提供凭据——这正是后文 GitHub Actions 自动化部署能够免交互运行的基础。

二、首次部署：npx partykit deploy

在项目目录下执行：

npx partykit deploy

CLI 会读取partykit.json中的name（项目名）和main（入口文件）完成部署。你也可以显式指定：npx partykit deploy src/server.ts --name my-project（见 partykit-cli.md 与 bin.tsx 中deploy命令的定义，deploy还设有publish别名）。

部署完成后，你的应用会获得一个partykit.dev子域名，命名模式为：

[项目名].[GitHub 用户名].partykit.dev

例如用户名为alice、项目名为my-project，则访问地址为https://my-project.alice.partykit.dev。从源码看，域名的拼接逻辑位于 cli.tsx：config.domain || ${config.name}.${config.team || user.login}.partykit.dev，即partykit.json中显式配置domain时优先使用自定义域名，否则按上述规则生成。

域名是首次部署后新申请的，CLI 会提示最多需要两分钟的 provisioning 时间（对应 cli.tsx 中is_initial_deploy分支的输出）。等待域名就绪后，就可以把链接分享给朋友在线体验了。

部署时到底发生了什么？

结合 cli.tsx 的deploy()实现，一次部署大致经历以下步骤：

1. 读取并校验配置：调用getConfig合并partykit.json、CLI 参数与.env文件；缺少main或name会分别抛出Missing entry point与Missing project name错误（对应测试见 deploy.test.ts）。
2. 执行构建钩子：若配置了build.command，先运行自定义构建命令（cli.tsx）。
3. 静态资源处理：若配置了serve，先通过 esbuild 构建前端资源，再计算 SHA-1 哈希、比对云端清单，只上传新增或变更的文件（cli.tsx）。
4. 打包服务端代码：用 esbuild 将入口文件连同parties、WASM/二进制模块一起打包（cli.tsx），并注入PARTYKIT_HOST等构建期常量。
5. 上传并发布：通过POST /parties/{user}/{name}提交代码（cli.tsx），服务端完成部署与域名调度。

这个调用链在 deploy.test.ts 中有完整的端到端验证：测试断言请求会命中/parties/test-user/test-script，并携带正确的访问令牌。

三、部署时注入环境变量

如果应用需要密钥（API Key、数据库口令等），有两种管理方式，详见 managing-environment-variables.md。

方式一：将密钥存到 PartyKit 平台（推荐）

在项目目录下执行（以API_KEY为例）：

npx partykit env add API_KEY

CLI 会提示你输入该变量的值。如需多个变量，重复执行即可。注意：新增的环境变量只在下次部署时生效，所以添加完毕后需要重新部署：

npx partykit deploy

对应源码中env add的实现（cli.tsx）会通过POST /parties/{user}/{name}/env/{key}将值写入平台，并用密码式输入（prompts的password类型）避免明文回显。你可以用npx partykit env list、npx partykit env pull、npx partykit env push、npx partykit env remove管理已部署的变量（命令定义见 bin.tsx）。

方式二：按单次部署临时注入（适合 CI）

如果某个部署想使用额外变量，或者你希望自己管理密钥（例如在 CI 环境中），可以在项目目录的.env文件中定义变量，然后执行：

npx partykit deploy --with-vars

请特别注意：--with-vars会覆盖平台中此前已部署的密钥值（仅对本次部署生效）。

如果不使用.env文件，也可以直接用命令行指定（下面示例同时注入API_KEY与HOST两个变量，取值来自你本地 shell 中已设置的同名环境变量）：

npx partykit deploy --var API_KEY=$API_KEY --var HOST=$HOST

从源码看，--with-vars与--var的语义差异非常明确（cli.tsx）：

• 使用--with-vars时，vars取config.vars——即partykit.json、.env、CLI 参数合并后的完整集合；
• 不使用--with-vars时，只会上传通过--var显式传入的变量，partykit.json与.env中的变量不会被带上。

这一行为在 deploy.test.ts 中被精确锁定：仅有--var时请求体是{"a":"b","c":"d"}；加上--with-vars: true后则合并为{"a":"b","b":"b2","c":"d","d":"d4"}。

补充说明：.env的读取发生在getConfig阶段（config.ts），CLI 会打印 "Loading environment variables from ..." 提示；仓库中的vars字段在配置参考中已标记为Deprecated（见 partykit-configuration.md），新项目请优先使用上述env命令体系。

四、线上调试：npx partykit tail

如果部署后的服务出现异常，可以在项目目录执行以下命令，实时获取线上流量日志与错误：

npx partykit tail

该命令会通过 WebSocket 订阅平台推送的实时事件流（包含请求、cron 定时任务、alarm、邮件等事件类型，结构见 tail/index.ts），并默认以易读的pretty格式打印：HTTP 请求显示为METHOD url - outcome @ 时间，异常会单独列出堆栈信息（打印逻辑见 tail/printing.ts）。进程退出时 CLI 会自动清理尾随会话（cli.tsx）。

更精准的日志过滤

tail命令内置了丰富的过滤选项（完整参数见 bin.tsx，参数到过滤器的转换见 tail/filters.ts）：

例如只查看 POST 请求的错误日志：

npx partykit tail --method POST --status error

五、配置 GitHub Actions：每次推送自动部署

官方部署指南推荐在项目稳定后接入 CI/CD，让每次推送到main分支都自动触发部署。完整步骤见 setting-up-ci-cd-with-github-actions.md，核心分为三步。

1. 生成 PartyKit 访问令牌

在本地执行：

npx partykit@latest token generate

浏览器完成授权后，CLI 会输出一对长期有效的会话凭据（源码实现见 cli.tsx）：

PARTYKIT_LOGIN=your_username PARTYKIT_TOKEN=eyJhb...YR7Bw

2. 在 GitHub 仓库中配置 Secrets

把上面两个值分别添加为 GitHub 仓库的PARTYKIT_LOGIN与PARTYKIT_TOKENSecrets。

:::caution 安全提醒PARTYKIT_TOKEN等同于你的部署权限——任何拿到它的人都能以你的身份部署 PartyKit 应用。切勿公开分享，也不要提交到版本库中。:::

3. 创建工作流文件

在项目根目录创建.github/workflows/deploy.yml：

name: Deploy on: push: branches: - main jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: actions/setup-node@v4 with: node-version: 18 cache: "npm" - run: npm ci - run: npx partykit deploy env: PARTYKIT_TOKEN: ${{ secrets.PARTYKIT_TOKEN }} PARTYKIT_LOGIN: ${{ secrets.PARTYKIT_LOGIN }}

这个工作流会在每次 push 到main分支时：检出代码 → 配置 Node.js 18 并启用 npm 缓存 → 安装依赖 → 以 Secrets 中的令牌执行部署。

之所以能在 GitHub Actions 中免交互部署，正是因为 config.ts 会优先读取PARTYKIT_LOGIN/PARTYKIT_TOKEN环境变量作为登录凭据，从而跳过浏览器授权环节。你完全可以在deploy之前插入自定义步骤（例如先跑测试、构建前端），或者按需部署到其他分支、使用--preview创建独立环境。

部署成功后，每次推送新代码都可以在仓库顶部 "Actions" 标签页实时查看工作流的运行输出。

六、进阶：预览环境与自定义域名

除了默认的生产域名，部署指南还推荐使用--preview为每次改动创建独立的预览环境（详见 preview-environments.md）：

npx partykit deploy --preview my-preview

部署结果会落在https://my-preview.my-project.alice.partykit.dev；测试完成后可删除：

npx partykit delete --preview my-preview

如果你希望将应用部署到自己的 Cloudflare 账户（cloud-prem 模式）并使用自定义域名，可以结合--domain与 Cloudflare 凭据（详见 deploy-to-cloudflare.md）：

CLOUDFLARE_ACCOUNT_ID=<your account id> CLOUDFLARE_API_TOKEN=<your api token> npx partykit deploy --domain partykit.domain.com

也可以将domain直接写入partykit.json；--domain与--preview可组合使用（https://my-preview.mydomain.com）。注意deploy的domain选项要求设置CLOUDFLARE_ACCOUNT_ID与CLOUDFLARE_API_TOKEN环境变量，否则会直接报错（cli.tsx）。

小结

从本地开发到生产上线，PartyKit 的部署链路可以用一条命令串起来：npx partykit deploy负责打包上传与域名分配，npx partykit env add+ 重新部署负责密钥注入，npx partykit tail负责线上实时排障，而token generate+ GitHub Actions 则把"提交即上线"变成自动化流水线。本文涉及的 CLI 命令均定义在 bin.tsx 中，对应的实现位于 cli.tsx，测试用例在 deploy.test.ts 与 tail.test.ts，可结合仓库源码进一步深入。

• 后端