deno-deploy

Deno Deploy

本技能提供将应用部署到 Deno Deploy 的指导。

范围界定

本技能仅适用于有关 Deno Deploy 的问题。请遵循以下规则：

• 如果用户询问 AWS Lambda、Vercel、Netlify、Google Cloud Run、 Docker、Kubernetes 或其他部署平台，请直接针对该平台作答。完全不要提及 Deno Deploy——不要将其作为替代方案、进行比较，也不要提出建议。
• 如果用户询问运行本地 Deno 脚本（而非部署），请直接回答本地运行问题。不要提及 Deno Deploy、部署或 --tunnel 标志。
• 回答有关其他平台或仅限本地脚本的问题时，不要包含 deno deploy 命令、Deno KV 或 Deno Deploy 环境变量配置。
• 仅当用户明确询问 Deno Deploy 或将 Deno 应用部署到生产环境时，才讨论 Deno Deploy。

重要：使用 deno deploy，不要使用 deployctl

始终使用 deno deploy 命令。 不要使用 deployctl。

• deployctl 用于 Deno Deploy Classic（已弃用）
• deno deploy 是现代化的集成命令，内置于 Deno CLI 中
• 需要 Deno >= 2.4.2——deno deploy 子命令在 Deno 2.4 中引入

不确定 CLI 标志时

猜测标志前，务必先运行 --help。 deno deploy 子命令有许多标志，且会因版本而异。如果不确定某个命令接受哪些参数：

# See all subcommands
deno deploy --help

# See flags for a specific subcommand
deno deploy create --help
deno deploy env --help
deno deploy database --help

这只需几秒钟，就能避免反复试错失败。不要假定某个标志存在——先检查。

部署工作流

始终先展示核心部署命令，然后再说明诊断步骤。用户询问“如何部署？”时，先给出实际命令（deno deploy --prod），再介绍部署前检查和配置。

第 1 步：定位应用目录

运行任何部署命令前，先找到 Deno 应用所在位置：

# Check if deno.json exists in current directory
if [ -f "deno.json" ] || [ -f "deno.jsonc" ]; then
  echo "APP_DIR: $(pwd)"
else
  # Look for deno.json in immediate subdirectories
  find . -maxdepth 2 -name "deno.json" -o -name "deno.jsonc" 2>/dev/null | head -5
fi

所有部署命令都必须在应用目录中运行。

第 2 步：部署前检查

检查 Deno 版本和现有配置：

# Check Deno version (must be >= 2.4.2)
deno --version | head -1

# Check for existing deploy config
grep -E '"org"|"app"' deno.json deno.jsonc 2>/dev/null || echo "NO_DEPLOY_CONFIG"

第 3 步：检查启动依赖项

部署前，检查应用启动时是否会连接数据库或外部服务（例如，在 main.ts 中执行顶层 await initDb()）。如果会，部署将在预热期间失败，因为数据库尚不存在。

如果应用在启动时依赖数据库，请按以下顺序操作：

1. 使用 --no-wait 创建应用，避免预热失败阻碍后续操作：

   deno deploy create \
     --org <ORG_NAME> --app <APP_NAME> \
     --source local --runtime-mode dynamic --entrypoint main.ts \
     --build-timeout 5 --build-memory-limit 1024 --region us \
     --no-wait
   

2. 配置并分配数据库：

   deno deploy database provision my-db --kind prisma --region us-east-1
   deno deploy database assign my-db --app <APP_NAME>
   

3. 重新部署（此时数据库已存在，预热将会成功）：

   deno deploy --prod
   

如果应用没有启动依赖项，请跳过此步骤，直接按下文所述正常部署。

第 4 步：根据配置部署

如果 deno.json 中存在 deploy.org 和 deploy.app：

# Build if needed (Fresh, Astro, etc.)
deno task build

# Deploy to production
deno deploy --prod

如果不存在部署配置：

必须先创建应用，才能部署到该应用。 在应用创建之前，无法运行 deno deploy --prod。

重要：请先询问用户——他们在 Deno Deploy 上是否已有应用， 还是需要创建一个新应用？

如果他们已有应用，请直接将配置添加到 deno.json：

{
  "deploy": {
    "org": "<ORG_NAME>",
    "app": "<APP_NAME>"
  }
}

组织名称可在 Deno Deploy 控制台 URL 中找到（例如， console.deno.com/your-org-name）。配置完成后，后续部署只需运行 deno deploy --prod。

如果他们需要创建新应用：

CLI 需要组织名称。请在 https://console.deno.com 查找—— 组织名称位于 URL 路径中（例如，console.deno.com/your-org-name）。

交互式创建（会打开浏览器——仅适用于有人使用键盘操作的情况）：

deno deploy create --org <ORG_NAME>
# A browser window opens - complete the app creation there

非交互式创建（AI Agent 执行部署或用于 CI/CD 时使用）：

deno deploy create \
  --org <ORG_NAME> \
  --app <APP_NAME> \
  --source local \
  --runtime-mode dynamic \
  --entrypoint main.ts \
  --build-timeout 5 \
  --build-memory-limit 1024 \
  --region us

创建命令也会执行首次部署。完成后，deno.json 会自动更新，添加 deploy.org 和 deploy.app。之后，后续部署只需运行：

deno deploy --prod

完成后，验证配置是否已保存：

grep -E '"org"|"app"' deno.json

AI Agent 执行部署时，始终使用带有显式标志的 非交互式流程。交互式流程需要打开浏览器窗口并响应终端提示，Agent 无法完成这些操作。

核心命令

生产部署

deno deploy --prod

预览部署

deno deploy

预览部署会生成一个唯一 URL，供测试使用，且不会影响 生产环境。

指定目标应用

deno deploy --org my-org --app my-app --prod

配置入口点

在 deno.json 中设置入口点（创建应用时，deno deploy create 会使用此配置）：

{
  "deploy": {
    "entrypoint": "main.ts"
  }
}

注意：--entrypoint 是 deno deploy create 的标志，而不是 deno deploy 本身的标志。

其他标志

以下标志可用于 deno deploy create（并会在首次 部署时生效）：

标志	用途
--allow-node-modules	在上传内容中包含 node_modules 目录
--no-wait	跳过等待构建完成

创建应用（非交互式参考）

提供除 --org 之外的任何标志时，deno deploy create 都会以 非交互模式运行——必须指定所有必需的标志。这是 AI Agent 和 CI/CD 流水线 推荐的方式。

必需标志

标志	描述
--org <name>	组织名称
--app <name>	应用名称（将成为你的 URL：<app>.deno.dev）
--source <local|github>	从本地文件或 GitHub 仓库部署
--build-timeout <minutes>	构建超时时间：5、10、15、20、25 或 30 分钟
--build-memory-limit <MB>	内存限制：1024、2048、3072 或 4096
--region <region>	部署区域：us、eu 或 global

GitHub 源代码标志

使用 --source github 时，还需要：

标志	描述
--owner <name>	GitHub 仓库所有者
--repo <name>	GitHub 仓库名称

构建配置标志

标志	描述
--app-directory <path>	应用目录的路径（用于 monorepo）
--framework-preset <preset>	框架预设（参见 框架）
--install-command <cmd>	自定义安装命令
--build-command <cmd>	自定义构建命令
--pre-deploy-command <cmd>	部署前运行的命令
--do-not-use-detected-build-config	跳过框架配置的自动检测

CLI 会自动检测你的框架和构建配置。如果检测到框架，你可以省略 --install-command、--build-command、--pre-deploy-command 和 --runtime-mode——系统会根据预设推断这些配置。使用 --do-not-use-detected-build-config 可覆盖检测结果。使用此标志时，必须提供全部三个构建命令（--install-command、--build-command、--pre-deploy-command）以及 --runtime-mode——省略其中任何一项都会导致退出码为 2。

运行时模式标志

你必须通过 --runtime-mode <dynamic|static> 选择一种运行时模式（除非框架预设已处理此项）。

动态模式（适用于带有服务器的应用）：

标志	描述
--entrypoint <path>	入口文件（动态模式必需）
--arguments <args>	传递给入口点的参数（可重复指定）
--working-directory <cwd>	进程的工作目录

静态模式（适用于静态网站）：

标志	描述
--static-dir <dir>	提供静态文件的目录（必需）
--single-page-app	对不匹配文件的路由提供 index.html

其他标志

标志	描述
--dry-run	验证所有内容，但不实际创建应用
--no-wait	不等待构建完成
--allow-node-modules	在上传内容中包含 node_modules

示例

简单的 Deno 服务器：

deno deploy create \
  --org my-org --app my-api \
  --source local \
  --runtime-mode dynamic --entrypoint main.ts \
  --build-timeout 5 --build-memory-limit 1024 --region us

新建应用（自动检测框架）：

deno deploy create \
  --org my-org --app my-fresh-app \
  --source local \
  --build-timeout 5 --build-memory-limit 1024 --region us

来自 GitHub 的 Next.js：

deno deploy create \
  --org my-org --app my-next-app \
  --source github --owner my-github-user --repo my-next-repo \
  --framework-preset Next \
  --build-timeout 15 --build-memory-limit 2048 --region us \
  --allow-node-modules

静态网站：

deno deploy create \
  --org my-org --app my-static-site \
  --source local \
  --runtime-mode static --static-dir dist --single-page-app \
  --build-command "deno task build" \
  --build-timeout 5 --build-memory-limit 1024 --region us

环境变量

上下文

Deno Deploy 有三个“上下文”——代码运行的逻辑环境，每个环境都有自己的一组变量：

上下文	用途
Production	生产 URL 上的实时流量
Development	预览部署和分支 URL
Build	仅在构建过程中可用

你可以为每个上下文中的同一个变量设置不同的值。例如，你可以在 Development 中使用测试数据库 URL，在 Production 中使用真实的数据库 URL。

预定义变量

这些变量会自动在你的代码中可用：

变量	描述
DENO_DEPLOY	在 Deno Deploy 上运行时始终为 1
DENO_DEPLOYMENT_ID	当前部署的唯一 ID
DENO_DEPLOY_ORG_ID	你所在组织的 ID
DENO_DEPLOY_APP_ID	你的应用 ID
CI	仅在构建期间设为 1

在代码中访问变量

const dbUrl = Deno.env.get("DATABASE_URL");
const isDenoDeploy = Deno.env.get("DENO_DEPLOY") === "1";

通过 CLI 管理变量

# Add a plain text variable
deno deploy env add DATABASE_URL "postgres://..."

# Add a secret variable (hidden after creation, only readable in code)
deno deploy env add API_KEY "sk-..." --secret

# List all variables
deno deploy env list

# Update just the value (keeps contexts and secret status)
deno deploy env update-value DATABASE_URL "postgres://new-url..."

# Update which contexts a variable applies to
deno deploy env update-contexts DATABASE_URL production development

# Delete a variable
deno deploy env delete DATABASE_URL

# Load from .env file (all values treated as secrets by default)
deno deploy env load .env.production

# Load from .env file, marking specific keys as non-secrets
deno deploy env load .env.production --non-secrets PUBLIC_URL APP_NAME

变量类型

• 纯文本 - 在控制台中可见，适用于功能开关和非敏感配置
• 密钥 - 创建后会隐藏，只能在代码中读取，适用于 API 密钥和凭据

限制

• 键名：最多 128 字节
• 值：最多 16 KB
• 键名不能以 DENO_、LD_ 或 OTEL_ 开头

查看日志

# Stream live logs
deno deploy logs

# Filter by date range
deno deploy logs --start 2026-01-15 --end 2026-01-16

数据库和存储

Deno Deploy 提供内置数据库支持，并具备自动环境隔离。每个环境（生产、预览、分支）都会自动获得独立的数据库。

可用选项

引擎	使用场景
Deno KV	键值存储、简单数据、计数器、会话
PostgreSQL	关系型数据、复杂查询、现有的 Postgres 应用

Deno KV 快速入门

无需配置——直接使用内置 API：

const kv = await Deno.openKv();

// Store data
await kv.set(["users", "alice"], { name: "Alice", role: "admin" });

// Retrieve data
const user = await kv.get(["users", "alice"]);
console.log(user.value); // { name: "Alice", role: "admin" }

// List by prefix
for await (const entry of kv.list({ prefix: ["users"] })) {
  console.log(entry.key, entry.value);
}

Deno Deploy 会根据你的环境自动连接到正确的数据库。

PostgreSQL

对于 PostgreSQL，Deno Deploy 会注入环境变量（DATABASE_URL、PGHOST 等），大多数库都能自动检测到这些变量：

// Recommended: npm:pg (best PostgreSQL driver for Deno Deploy)
import pg from "npm:pg";
const pool = new pg.Pool(); // Reads DATABASE_URL from environment automatically

配置数据库

使用 deno deploy database 命令来配置和管理数据库：

# Provision a Deno KV database
deno deploy database provision my-database --kind denokv

# Provision a Prisma PostgreSQL database
deno deploy database provision my-database --kind prisma --region us-east-1

# Assign to your app
deno deploy database assign my-database --app my-app

如需查看详细的 CLI 命令，请参阅 数据库。

本地开发

使用 --tunnel 在本地连接到托管的开发数据库：

deno task --tunnel dev

如需查看详细文档，请参阅 数据库 和 Deno KV。

本地开发隧道

隧道功能可将本地开发服务器暴露到互联网。这适用于：

• 测试 Webhook - 接收来自外部服务的 Webhook 回调
• 与队友分享 - 让其他人预览你的本地工作
• 移动端测试 - 从其他设备访问本地服务器

基本用法

运行应用时添加 --tunnel 标志：

deno run --tunnel -A main.ts

首次运行时，它会：

1. 要求你通过 Deno Deploy 进行身份验证（会打开浏览器）
2. 要求你选择要连接隧道的应用
3. 生成一个将请求转发到本地服务器的公开 URL

与任务配合使用

你可以在 deno.json 中将 --tunnel 与现有任务配合使用：

deno task --tunnel dev

这会在启用隧道的情况下运行你的 dev 任务。

隧道提供的功能

除了转发请求之外，隧道还会：

• 同步环境变量 - 在 Deno Deploy 应用的 “Local” 上下文中设置的变量会在本地进程中可用
• 发送日志和指标 - OpenTelemetry 数据会发送到 Deno Deploy 控制台（使用 context:local 筛选）
• 连接数据库 - 自动连接到分配给你的本地开发数据库

管理隧道

• 在 Deno Deploy 控制台的 “Tunnels” 选项卡中查看活动隧道
• 终止 Deno 进程（Ctrl+C）即可停止隧道

命令参考

命令	用途
deno deploy --prod	部署到生产环境（必须先创建应用）
deno deploy	预览部署
deno deploy create --org <name>	创建新应用（交互式）
deno deploy create --org <name> --app <name> ...	创建新应用（非交互式，参见上方完整标志）
deno deploy create ... --no-wait	创建应用后不等待构建完成
deno deploy create ... --allow-node-modules	创建包含 node_modules 的应用
deno deploy env add <var> <value>	添加纯文本环境变量
deno deploy env add <var> <value> --secret	添加机密环境变量
deno deploy env list	列出环境变量
deno deploy env update-value <var> <value>	更新变量值（保留上下文和机密状态）
deno deploy env update-contexts <var> <contexts...>	更新变量适用的上下文
deno deploy env delete <var>	删除环境变量
deno deploy env load <file>	从 .env 文件加载变量（默认为机密变量）
deno deploy env load <file> --non-secrets <keys...>	加载 .env 文件，并将指定键标记为非机密
deno deploy database provision <name> --kind <type>	配置新数据库
deno deploy database assign <name> --app <app>	将数据库分配给应用
deno deploy logs	查看部署日志
deno run --tunnel -A <file>	启动本地隧道
deno task --tunnel <task>	通过隧道运行任务

边缘运行时说明

Deno Deploy 在一个或多个区域运行（全球分布）。请注意：

• 环境变量 - 必须通过 deno deploy env 设置，不能在运行时通过 .env 文件设置
• 全球分布 - 代码在距离用户最近的区域运行
• 冷启动 - 空闲后的首次请求可能会稍慢

更多参考资料

• 身份验证 - 交互式身份验证和 CI/CD 身份验证
• 数据库 - 数据库配置与连接
• Deno KV - 键值存储 API 和示例
• 域名 - 自定义域名和 SSL 证书
• 框架 - 特定框架的部署指南
• 组织 - 管理组织和成员
• 运行时 - 生命周期、冷启动和限制
• 故障排除 - 常见问题及解决方案

Documentation

• Official docs: https://docs.deno.com/deploy/
• CLI reference: https://docs.deno.com/runtime/reference/cli/deploy/
• Databases: https://docs.deno.com/deploy/reference/databases/
• Deno KV: https://docs.deno.com/deploy/reference/deno_kv/
• Domains: https://docs.deno.com/deploy/reference/domains/
• Environment variables & contexts: https://docs.deno.com/deploy/reference/env_vars_and_contexts/
• Organizations: https://docs.deno.com/deploy/reference/organizations/
• Runtime: https://docs.deno.com/deploy/reference/runtime/
• Tunnel: https://docs.deno.com/deploy/reference/tunnel/