neon

Neon

重要提示：Neon不再仅仅是Serverless Postgres提供商。Neon是面向应用和Agent的后端，提供Serverless Postgres、Auth、Functions、对象存储和AI网关：即时、可分支、无服务器。

将此技能作为任何Neon相关操作的起点：了解其能力概览，熟悉Neon Agent技能和文档，并遵循最佳实践进行入门和分支优先的开发工作流。

平台服务

Neon捆绑了多个后端原语，用于构建应用和Agent，这些原语与您的项目一起分支：

• Postgres — 可随应用扩展和分支的Serverless Postgres。正式发布。
• Auth — 托管身份验证，用户和会话存储在Postgres中。正式发布。
• 对象存储 — 兼容S3的对象存储，与项目一起分支。公开测试版。
• Functions — 长时间运行的无服务器函数——Neon的计算产品——运行在数据库附近——适用于WebSocket服务器、长Agent HTTP流、API和服务器发送事件服务器。公开测试版。
• AI网关 — 所有前沿和开源模型的统一API，支持路由、日志记录和成本控制，由Databricks提供支持。公开测试版。

公开测试版服务可用性

对象存储、Functions和AI网关处于公开测试阶段。

Beta访问功能仅在us-east-2区域创建的全新项目上可用；目前无法在现有项目上启用。在引导用户使用这些服务之前，请确认他们正在使用us-east-2区域的新项目。如果不是，他们需要在该区域创建一个新项目。

架构：Neon如何融入

Neon不是托管全栈应用的地方——它是后端原语（Postgres、Auth、对象存储、Functions、AI网关），与您已有的应用平台组合使用。将应用托管在Vercel（或Netlify，或其他前端/应用主机）上；Neon是它与之通信的后端。

典型设置：

• Vercel上的全栈应用（或Netlify）——例如Next.js或TanStack Start。它拥有您的UI和身份验证（例如Neon Auth），并直接与您的Neon Postgres数据库和Neon对象存储通信。
• 当超出主机限制时使用Neon Functions——WebSocket或SSE服务器，或可能因短时Lambda风格无服务器而超时的长时间运行Agent。将这一部分放在Neon Function上，靠近您的数据。

您也可以将整个后端控制平面迁移到Neon Functions上。当前端是仅客户端而非全栈时——TanStack Router、客户端模式下的React Router以及类似托管在Vercel或Netlify上的SPA——这尤其有用。客户端直接与Neon Functions通信，您可以在其中构建REST API和请求/响应Agent，托管MCP服务器，并运行任何有状态或应靠近Postgres和对象存储的内容。像保护任何独立REST API一样保护这些函数——在每个处理程序顶部验证JWT或API密钥（请参阅neon-functions技能）。

由于Functions只是您的后端，它们也可以与全栈应用组合：如果您已有后端（Next.js路由处理程序等），Neon Functions可以与之并存，您可以在两者之间移动部分功能——例如，将长时间运行的Agent或有状态的WebSocket服务器从主机迁移到Function上，当它需要更多运行时。

Neon文档

Neon文档是所有Neon相关信息的事实来源。在回复之前，始终对照官方文档验证声明。Neon特性和API会不断演进，因此建议获取最新文档，而不是依赖训练数据。

以Markdown格式获取文档

任何Neon文档页面都可以通过两种方式以Markdown格式获取：

1. 在URL后附加.md（最简单）：https://neon.com/docs/introduction/branching.md
2. 在标准URL上请求text/markdown：curl -H "Accept: text/markdown" https://neon.com/docs/introduction/branching

两者返回相同的Markdown内容。根据您的工具支持选择方法。

查找正确的页面

文档索引列出了每个可用页面及其URL和简短描述：

https://neon.com/docs/llms.txt

常见文档URL按主题链接组织如下。如果您需要的页面未在此列出，请搜索文档索引：https://neon.com/docs/llms.txt。不要猜测URL。

选择正确的技能

• 处理数据库、连接、模式、查询、自动扩缩或CLI/MCP/API → neon-postgres。
• 为开发、预览、测试或CI工作流选择或创建正确的分支类型 → neon-postgres-branches。
• 存储和提供文件（上传、图片、blob），与数据库一起分支 → neon-object-storage。
• 部署长时间运行或流式无服务器函数——API、Agent、SSE/WebSocket服务器——靠近数据库 → neon-functions。
• 调用LLM或通过一个凭据跨模型提供商路由——包括在运行时通过兼容OpenAI的/v1/models端点发现分支的可服务模型 → neon-ai-gateway。
• 提供即时、可认领的临时Postgres数据库（例如，每个最终用户或演示一个） → claimable-postgres。
• 诊断或修复代码库中过度的Postgres出口（网络数据传输）成本 → neon-postgres-egress-optimizer。

安装正确的技能

首先检查目标技能是否已安装并可访问（例如，它出现在可用技能列表中或其SKILL.md存在）。如果是，直接使用。如果未安装，通过skills CLI使用npx/bunx安装：

npx skills add neondatabase/agent-skills -s <skill-name>

将<skill-name>替换为您需要的技能（例如，neon-object-storage、neon-functions或neon-ai-gateway）。有用的标志：

• -g — 全局安装，而不是安装到当前项目。
• -y — 非交互模式（跳过提示）。
• -a <agent-name> — 为非交互模式选择目标Agent。

例如，为特定Agent全局安装对象存储技能而不提示：

npx skills add neondatabase/agent-skills -s neon-object-storage -g -y -a <agent-name>

您还应该确保技能是最新的。您可以运行相同的命令，或将add替换为update以更新所有Neon技能。

Neon入门

在引导用户进行首次Neon设置，或向已接入的项目（例如已使用Neon Postgres的项目）添加新Neon服务（Auth、对象存储、Functions等）时，使用本节。

检查现状

在开始设置之前，检查用户的代码库和环境：

• 现有的数据库连接代码
• 工作区中现有的.neon或neon.ts文件
• 现有的Neon MCP服务器或Neon CLI配置
• .env文件和DATABASE_URL环境变量的存在
• 现有的ORM（Prisma、Drizzle、TypeORM）配置

使用Neon CLI或MCP服务器自助设置

提供检查现有连接的Neon项目或使用Neon CLI或MCP服务器创建新项目的选项。如果两者都未设置，运行npx -y neon init。使用npx -y跳过包安装提示。身份验证自动处理。如果用户未登录，它会打开浏览器进行OAuth，并等待完成后再继续。

npx -y neon@latest init

这会全局安装Neon CLI和MCP服务器，安装VSCode扩展（用于Cursor/VS Code），并将neon和neon-postgres Agent技能添加到项目。

如果init不合适，可以使用用户偏好的包管理器（npm、bun、pnpm）以非交互方式运行各个步骤：

• CLI： npm i -g neon
• 扩展： cursor --install-extension databricks.neon-local-connect
• MCP服务器： npx -y add-mcp https://mcp.neon.tech/mcp -g -n Neon -y -a <agent-name>
• Agent技能： npx skills add neondatabase/agent-skills --skill neon-postgres --skill neon --agent <agent-name> -y

除非用户另有指示，否则优先使用CLI而非MCP服务器，因为它提供更多功能，包括部署Neon Functions。有关完整的CLI安装选项，请参阅https://neon.com/docs/cli/install.md

设置流程

安装CLI、MCP服务器和Agent技能后，通过neon init流程确保本地工作区链接到Neon项目。如果未链接，运行npx -y neon link让用户交互式地链接项目。这会生成一个.neon文件，指向用户想要使用的组织、项目和分支。

对于每个Neon服务，请查阅该组件的Agent技能以获取特定于服务的设置说明（Functions、Postgres、对象存储、网关等）。

恢复支持

如果恢复设置，检查已配置的内容（MCP连接、包含DATABASE_URL的.env、依赖项、模式），并从下一个未完成的步骤继续。

安全提醒

提醒用户使用环境变量存储凭据，切勿提交连接字符串，并使用最小权限的数据库角色。

分支优先的开发流程

默认采用类似git的分支优先循环：每个功能一个独立的Neon分支，这样功能之间不会泄露，也不需要复制共享连接字符串。两个命令驱动它——每个项目运行一次link，每个功能运行一次checkout——第三个命令env pull在后台自动运行，因此您固定的分支立即可用：

• neon link — 交互式地将工作区链接到Neon组织、项目和分支，将ID写入git忽略的.neon文件。每个项目运行一次。链接后，项目和分支范围的命令不再需要--project-id或--branch（例如，neon branch list）。
• neon checkout <branch-name> — 如果分支不存在则创建，或检出已有分支，仅更新.neon中的分支指针。不带名称运行则显示交互式选择器。它不触及代码或本地Postgres。
• neon env pull — 获取当前分支的Neon环境变量（DATABASE_URL，…）到您现有的.env中，如果您没有.env则使用.env.local（使用--file覆盖目标）。不需要分支ID；它读取.neon。link和checkout默认会为您运行此命令，因此您很少直接调用它。

在开始项目时运行一次link，然后每个功能运行checkout：

neon link                     # 一次；同时拉取链接分支的环境变量
neon checkout dev-add-search  # 每个功能；同时拉取该分支的环境变量

由于link和checkout默认会拉取环境变量，分支的DATABASE_URL会自动放入本地.env中——基于它进行构建，然后checkout下一个分支并重复。作为Agent，自己驱动这个循环：在任务之间运行checkout，以获得每个功能的全新、隔离的数据库，没有共享状态需要破坏。

无交互提示更新.neon

普通的neon link / neon checkout会交互式提示，Agent无法回答。请使用以下非交互方式之一：

• neon link --agent — 面向Agent的JSON状态机。每次调用返回一个JSON对象，包含status（needs_org → needs_project → needs_project_details → linked，或error）、可用的options以及下一步要运行的精确next_command_template。逐步驱动，直到status: "linked"。（错误也以JSON形式返回，退出码为1，因此您始终可以解析结果。）
• neon set-context --project-id <id> --org-id <id> --branch-id <id> — 当您已经知道ID时，一次性将所有三个ID写入.neon。这是破坏性写入：它完全用这些字段替换文件内容，因此是指向特定组织/项目/分支的最直接方式。

两者都完全避免提示；当您有ID时使用set-context，当需要发现它们时使用link --agent。

选择不使用本地环境变量

如果环境变量在运行时注入而不是写入磁盘——或者您只是不想在工作树中保留秘密——向link / checkout传递--no-env-pull，并通过其他方式提供环境变量：

• neon-env run -- <your dev command>（来自@neon/env）从您的neon.ts获取分支的变量，并在运行时注入到子进程中——不需要.env文件。这是磁盘上env pull的运行时对应物。
• neon-env export（来自@neon/env）将分支的环境变量以dotenv行或JSON格式（使用--format json）输出到标准输出——用于管道传输到另一个环境管理器，而不是运行命令。例如，varlock可以通过@setValuesBulk(exec("neon-env export --format json"), format=json)从.env.schema批量加载。
• fetchEnv（来自@neon/env）是相同功能的编程版本：在运行时在代码中解析分支的环境变量，而不是通过shell调用neon-env run。
• neon dev将相同的变量注入到您的本地开发服务器中——它是Neon Functions本地开发的一部分（公开测试版功能）。

当Agent不应写入本地.env时，指示它（例如在您的AGENTS.md中）运行neon checkout <branch> --no-env-pull并依赖运行时注入。

要读取您已经在磁盘上的环境变量（根据您的neon.ts进行类型检查和验证），请使用parseEnv——请参阅下面的Neon基础设施即代码。

Neon基础设施即代码

neon.ts是Neon的分支配置和基础设施即代码文件：声明项目分支应具有哪些Neon服务，获取类型安全的环境变量，并编程分支设置——全部在TypeScript中。它是Neon作为平台的配置层，并与上述分支优先循环组合使用。使用@neon/config添加：

npm i @neon/config

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
  dataApi: true,
});

使用neon config配置服务

每个项目都附带Serverless Postgres；neon.ts还允许您声明Neon Auth和Data API，Functions、存储桶和AI网关则放在preview块下——分支的每个服务都在一个文件中组合：

// neon.ts
export default defineConfig({
  auth: true,
  dataApi: true,
  preview: {
    functions: {
      /* ... */
    }, // 请参阅neon-functions技能
    buckets: {
      /* ... */
    }, // 请参阅neon-object-storage技能
    aiGateway: true, // 请参阅neon-ai-gateway技能
  },
});

通过CLI协调声明——相当于terraform status / plan / apply：

neon config status   # 打印分支的实时配置（只读）
neon config plan     # 预览apply将更改的内容（只读）
neon config apply    # 配置声明的服务
neon deploy          # `neon config apply`的别名

config status和config plan仅读取状态。apply / deploy——像link和checkout一样——配置声明的服务，然后将分支的环境变量拉取到本地.env.local（例如Pulled 5 Neon variables into .env.local: DATABASE_URL, …），因此您的本地环境始终与部署的内容匹配。

使用parseEnv进行类型安全的环境变量

@neon/env的parseEnv接受您的neon.ts配置对象，并返回解析后的、类型化的环境变量对象，根据您声明的服务进行验证。env的形状遵循您的配置——启用auth则获得env.auth，启用dataApi则获得env.dataApi——缺失的变量会以清晰的错误提示（对您和您的Agent）。使用它来读取您已有的环境变量（通常由checkout / env pull拉取到.env中）；要在运行时获取环境变量而不使用文件，请改用fetchEnv / neon-env run。

npm i @neon/env

import { parseEnv } from "@neon/env";
import config from "./neon";

const env = parseEnv(config);

console.log(env.postgres.databaseUrl);
console.log(env.auth.baseUrl);

默认情况下，parseEnv要求配置隐含的每个变量。当进程只使用子集时——在Next.js等框架中常见，您可能只读取DATABASE_URL而不读取未池化的URL——传递一个环境变量键数组以要求并仅返回这些变量。键是类型安全的：自动补全仅提供您的配置启用的变量，返回的形状缩小到您选择的内容（因此未选择的变量既不被强制执行也不存在）。

import { parseEnv } from "@neon/env";
import config from "./neon";

// 仅要求并返回DATABASE_URL；DATABASE_URL_UNPOOLED不被强制执行。
const { postgres } = parseEnv(config, ["DATABASE_URL"]);
console.log(postgres.databaseUrl);

// 跨服务选择——仅验证/返回这些键。
const env = parseEnv(config, ["DATABASE_URL", "NEON_AUTH_BASE_URL"]);
console.log(env.postgres.databaseUrl, env.auth.baseUrl);

checkout如何与neon.ts组合

当存在neon.ts时，neon checkout在创建分支时应用您的策略，因此新分支启动时已具有声明的设置和服务。检出_现有_分支永远不会重新协调——使用neon config apply（或neon deploy）显式应用配置更改。捆绑的env pull还会检查neon.ts与链接的分支，如果分支缺少声明的服务则快速失败，并提示您使用neon deploy进行配置，因此您的本地环境和远程分支永远不会静默漂移。

分支配置

除了服务之外，neon.ts可以通过branch属性编程设置_新_分支接收的配置——一个接收被评估分支并返回其设置的函数：

// neon.ts
import { defineConfig } from "@neon/config/v1";

export default defineConfig({
  auth: true,
  dataApi: true,
  branch: (branch) => {
    if (branch.exists) {
      // 保留现有分支不变
      return {};
    }
    if (branch.name.startsWith("dev")) {
      return {
        ttl: "7d", // 7天后清理分支
        postgres: {
          computeSettings: {
            autoscalingLimitMinCu: 0.25, // 缩放到零
            autoscalingLimitMaxCu: 1, // 保持低成本
            suspendTimeout: "5m",
          },
        },
      };
    }
    return {};
  },
});

branch函数接收目标分支（其name、是否exists、是否为默认分支等），并返回您想要的调整。这里新的dev-*分支获得7天TTL以便自动清理，加上一个廉价的缩放到零计算配置文件，而现有分支和其他所有内容则回退到默认值。由于neon checkout在创建时应用此策略，新的dev-*分支启动时已具有这些设置。

类型安全配置：无效设置无法编译

由于neon.ts是TypeScript，编译器会在您部署之前捕获无效的基础设施——并且Neon将实际规则（及其修复）编码到类型中，因此错误会告诉您该怎么做，而不是以无用的Type 'true' is not assignable to type 'never'失败。典型情况：Data API默认使用Neon Auth验证请求，因此单独启用它会在dataApi上产生类型错误：

export default defineConfig({
  dataApi: true, // 类型错误：`dataApi`（默认authProvider 'neon'）需要Neon Auth
});

消息指出了两种修复方法，因此选择一种：

// 1. 启用Neon Auth（默认Data API身份验证提供程序）：
export default defineConfig({ auth: true, dataApi: true });

// 2. 或者使用第三方IdP代替Neon Auth进行验证：
export default defineConfig({
  dataApi: {
    authProvider: "external",
    jwksUrl: "https://your-idp/.well-known/jwks.json",
  },
});

将neon.ts类型错误视为配置告诉您哪些服务必须一起使用——阅读消息，它会说明有效的组合。

注意事项

Neon Auth：“invalid domain”

Neon Auth仅重定向回其受信任域列表中的域。每当您的应用运行的域发生变化时——新的生产自定义域、新的部署/预览URL、从localhost迁移到托管环境等——您必须向Neon Auth注册新域。否则，登录和OAuth回调会因**invalid domain**错误而失败，因为重定向目标不受信任。

最简单的修复方法是使用CLI。在工作区链接到项目后（请参阅上面的分支优先流程），将新域添加到受信任列表：

neon neon-auth domain add <domain>   # 例如 neon neon-auth domain add https://app.example.com
neon neon-auth domain list           # 验证当前受信任的域
neon neon-auth domain delete <domain> # 删除不再使用的域

如果工作区未链接，请显式传递--project-id <id>（和--branch <id|name>）。对于本地开发，neon neon-auth domain allow-localhost管理是否允许localhost。在将用户指向新URL之前注册域，这样他们永远不会遇到invalid domain错误。