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>	应用目录的路径（用于单体仓库）
--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 有三个“上下文”——代码运行的逻辑环境，每个环境都有各自的一组变量：

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

你可以为每个上下文中的同一变量设置不同的值。例如，你可以在开发环境中使用测试数据库 URL，在生产环境中使用真实的数据库 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

与任务配合使用

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

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 证书
• 框架 - 特定框架的部署指南
• 组织 - 管理组织和成员
• 运行时 - 生命周期、冷启动和限制
• 故障排除 - 常见问题和解决方案

文档

• 官方文档：https://docs.deno.com/deploy/
• CLI 参考：https://docs.deno.com/runtime/reference/cli/deploy/
• 数据库：https://docs.deno.com/deploy/reference/databases/
• Deno KV：https://docs.deno.com/deploy/reference/deno_kv/
• 域名：https://docs.deno.com/deploy/reference/domains/
• 环境变量和上下文：https://docs.deno.com/deploy/reference/env_vars_and_contexts/
• 组织：https://docs.deno.com/deploy/reference/organizations/
• 运行时：https://docs.deno.com/deploy/reference/runtime/
• 隧道：https://docs.deno.com/deploy/reference/tunnel/