meteor-deployment

Meteor 部署

meteor build 会生成一个自包含的 Node 程序包，可在能够运行相应 Node.js 版本的任何环境中运行。Galaxy 是官方托管平台；Docker / Kubernetes / SSH 到 Node 主机也都可行。

对于 Android/iOS 构建产物和原生 HCP 兼容性，请使用 meteor-native。除了兼容性哈希值，也要检查实际的原生配置：权限或其他原生配置变更可能需要重新构建二进制文件，即使哈希值没有变化。

Node 版本应与捆绑的 Meteor Node 版本匹配：

Meteor	Node 主版本
3.0	20
3.1 到 3.4	22
3.5.x 和 3.6-beta.0	24
3.6-beta.1 到 beta.3	26 (26.8.2)
3.6-rc.0	26 (26.10.0)

在目标应用中运行 meteor node -v 和 meteor npm -v 进行确认。 Meteor 3.6-beta.1 到 beta.3 捆绑了 npm 11.19.0。部署运行时和原生依赖构建环境应与该版本匹配；部署这些 beta 版本前，请针对 Node 26 和生产架构重新构建并测试原生 npm 模块。 Meteor 3.6-rc.0 捆绑了 npm 11.19.1。提取的程序包会在 bundle/.node_version.txt 中记录精确的 Node 版本；源工具不可用时，请使用此元数据。主机安装程序的先决条件不会决定捆绑的运行时版本。

决策流程

1. 使用 Galaxy？选择 Git Push to Deploy 或 Meteor CLI。请参阅 references/galaxy.md，配置 Galaxy 的设置来源、构建钩子、健康检查和域名。
2. 使用 Docker / Kubernetes？meteor build --directory ./build --server-only 会跳过特定于平台的移动端构建产物。跨平台构建时使用 --architecture os.linux.x86_64。
3. SSH 到 Node 主机？使用相同的 meteor build，通过 scp 复制程序包，在 bundle/programs/server 下安装生产依赖，然后运行 node main.js。
4. 使用 Vercel / Netlify / 无服务器平台？不支持。Meteor 需要一个 长期运行且支持 WebSocket 的 Node 进程。

对于已链接的工作区包，请将程序包移到检出目录之外，并在没有源码访问权限的情况下测试所用的 .bin 命令和相邻资源读取。 3.6-beta.3 修复了复制后的命令链接；依赖这些链接前，请先验证旧版工具。保留包管理器和锁文件，不要修补生成的链接。 有关 beta.3 的本地 MongoDB 8 与外部数据库，请参阅数据库边界。

必需的环境变量

Var	用途
ROOT_URL	外部绝对 URL（例如 https://app.example.com）。
MONGO_URL	mongodb://... 连接字符串。
MONGO_OPLOG_URL	可选的 Mongo 副本 oplog URL。
PORT	监听端口。默认值为 3000。
BIND_IP	网络接口。默认值为 0.0.0.0。
METEOR_SETTINGS	JSON；用于填充 Meteor.settings。
MAIL_URL	用于 Email.send 和账户邮件的 SMTP。

ROOT_URL 是浏览器看到的外部 URL，而不是集群内部服务 URL。OAuth 重定向、Meteor.absoluteUrl 和 CSP 都依赖它。

在 Meteor 3.0 到 3.4 中，配置 MONGO_OPLOG_URL 以启用基于 oplog 的响应式更新；如果未配置，Meteor 会轮询。Meteor 3.5+ 无需此变量即可使用核心变更流，并会在需要时回退到 oplog 或轮询。仅使用 Atlas 托管，并不会让较旧的 Meteor 应用获得核心变更流支持。

settings.json

{
  "public": { "appName": "My App", "stripePublishableKey": "pk_live_..." },
  "stripeSecretKey": "sk_live_...",
  "oauthSecretKey": "16-byte-base64==",
  "mailgun": { "apiKey": "..." }
}

顶层键：仅服务器可见。public 子树：会发送到客户端。

加载：

# dev
meteor run --settings settings.json

# production
METEOR_SETTINGS=$(cat settings.json) node bundle/main.js

Galaxy

选择一种部署方式：

方式	适用情况	触发条件
Push to Deploy	Galaxy 应构建已连接的 GitHub 或 Bitbucket 分支。	每次向选定分支推送时。
Meteor CLI	由人员或 CI 流水线控制每次上传。	meteor deploy <app-name>。

检查 meteor whoami；添加 --owner my-account 以选择特定用户或组织。对于新的 Free 应用，传入简单的应用名称，而不是自定义域名：

meteor login
meteor deploy myapp --free --settings settings.json

DEPLOY_HOSTNAME=eu-west-1.galaxy-deploy.meteor.com \
  meteor deploy myapp --plan essentials --settings settings.json

Galaxy 会在 Free 方案下分配 myapp.sandbox.galaxycloud.app 主机名，或在付费方案下分配区域性的 myapp.<region>.galaxycloud.app 主机名。在控制面板中添加自定义域名。当前启用的主域名决定 ROOT_URL。

对于现有应用，重新部署前请确认其当前主机名、区域和所有者。--plan 和 --container-size 用于选择创建设置；要更改现有应用的方案或大小，请在控制面板中操作。也可以添加 --mongo，为测试配置免费的共享 MongoDB，并遵循 Mongo TLS 指南。它没有备份功能，不建议用于生产环境。

Galaxy 会注入 PORT、ROOT_URL 和 METEOR_SETTINGS。将 MONGO_URL、MAIL_URL 及其他服务器环境值放在 Galaxy 设置 JSON 的 galaxy.meteor.com.env 下。不要假设 CLI 的 --settings 文件会覆盖 Repository Mode。

请参阅 references/galaxy.md，了解设置模式、Push to Deploy 构建、零停机发布和回滚、代理、Mongo TLS、内存及自定义基础镜像。

Docker

请参阅 references/docker.md 获取可用的多阶段 Dockerfile。在一个阶段构建 bundle，在另一个较小的阶段安装服务器依赖并运行。--server-only 会跳过特定于平台的移动应用构建，但不会省略浏览器客户端，也不会创建仅含 API 的 bundle。Meteor 仍会构建用于热代码推送的 web.cordova 客户端目标。

热代码推送

autoupdate 提供生产环境中的热代码推送。它会通过 DDP 检测新客户端版本，在可能的情况下仅应用样式表更改而不重新加载，否则会完整重新加载浏览器。要禁用 HCP，请从 .meteor/packages 中移除 autoupdate。

hot-module-replacement 则不同。它会在开发期间替换已接受的 JavaScript 模块；如果模块无法接受更新，则回退到 HCP。HMR 在生产环境和不受支持的 Web 架构上会被禁用。当前公开 API 中没有 Meteor.disableClientResourceFetch 开关。

反模式

• 提交包含生产密钥的 settings.json。使用 CI 密钥存储或环境变量；在启动时通过 METEOR_SETTINGS=$(cat ...) 加载。
• 将 ROOT_URL 设为内部 Kubernetes 服务 URL。应使用外部 HTTPS URL，否则 OAuth 重定向和 Meteor.absoluteUrl 会失效。
• 运行的 Node 版本与打包的 Meteor Node 不匹配。务必检查 meteor node -v。
• 在错误的架构上构建。在 M 系列 Mac 上开发、为 x86_64 Linux 构建时，必须传入 --architecture os.linux.x86_64。
• 提交含凭据的 Galaxy 设置，或期望 Repository Mode 读取 CLI 的 --settings 文件。将密钥保存在 Galaxy Mode 或密钥存储中。
• 对 Galaxy 的端口、负载均衡器 IP 或区域 DNS 目标进行硬编码。读取 $PORT，并从应用控制面板复制当前网络值。
• 将源代码树与构建好的 bundle 一同打包进 Docker 镜像。使用多阶段构建；运行时镜像中只保留 bundle/。

另请参阅

• references/settings-and-env.md
• references/galaxy.md
• references/docker.md
• references/eval-cases.md