边缘函数

依赖管理

管理包与依赖项

导入依赖项

Supabase 边缘函数支持多种导入依赖项的方式：

NPM 模块

可以使用 npm: 说明符导入 npm 模块：

1
import { createClient } from 'npm:@supabase/supabase-js@2'

Node.js 内置模块

对于 Node.js 内置 API，使用 node: 说明符：

1
import  from 'node:process'

更多关于 npm 说明符和 Node 内置 API 的信息，请参阅 Deno 文档。

JSR

可以使用 jsr: 说明符导入发布到 JSR 的 JS 模块（例如 Deno 的标准库）：

1
import path from 'jsr:@std/path@1.0.8'

管理依赖项

使用边缘函数开发与使用 Node.js 开发类似，但有几个关键区别。

在 Deno 生态系统中，每个函数都应被视为具有自己依赖项和配置的独立项目。这种"设计隔离"的方法：

  • 确保每个函数对其依赖项有明确控制
  • 防止函数之间产生意外副作用
  • 使部署更可预测和可维护
  • 允许不同函数使用同一依赖项的不同版本

因此，我们建议在每个函数目录中维护单独的配置文件（deno.json、.npmrc 或 import_map.json），即使这意味着需要重复某些配置。

在 Supabase 边缘函数中有两种管理依赖项的方式：

使用 deno.json（推荐方式）

每个函数都应拥有自己的 deno.json 文件来管理依赖项并配置 Deno 特定设置。这能确保函数间的正确隔离，是推荐的部署方式。完整支持选项列表请参阅 Deno 官方配置文档。

1
2
3
4
5
{  "imports": {    "lodash": "https://cdn.skypack.dev/lodash"  }}

推荐的部署文件结构：

1
2
3
4
5
6
7
8
9
10
11
└── supabase    ├── functions    │   ├── function-one    │   │   ├── index.ts    │   │   ├─- deno.json    # 函数特定的 Deno 配置    │   │   └── .npmrc       # 函数特定的 npm 配置（如需要）    │   └── function-two    │       ├── index.ts    │       ├─- deno.json    # 函数特定的 Deno 配置    │       └── .npmrc       # 函数特定的 npm 配置（如需要）    └── config.toml

使用导入映射（传统方式）

导入映射（Import Maps）是一种传统的依赖管理方式，类似于 package.json 文件。虽然仍受支持，但我们推荐使用 deno.json。如果两者同时存在，deno.json 会优先生效。

每个函数应有自己的 import_map.json 文件以实现正确隔离：

1
2
3
4
5
{  "imports": {    "lodash": "https://cdn.skypack.dev/lodash"  }}

推荐的文件结构：

1
2
3
4
5
6
7
8
9
└── supabase    ├── functions    │   ├── function-one    │   │   ├── index.ts    │   │   └── import_map.json    # 函数专属导入映射    │   └── function-two    │       ├── index.ts    │       └── import_map.json    # 函数专属导入映射    └── config.toml

如果在 VSCode 中使用导入映射，请更新 .vscode/settings.json 指向函数专属的导入映射：

1
2
3
4
5
6
7
8
9
{  "deno.enable": true,  "deno.unstable": [    "bare-node-builtins",    "byonm"    // ... 其他标志 ...  ],  "deno.importMap": "./supabase/functions/my-function/import_map.json"}

您可以通过以下方式覆盖默认的导入映射位置：

  • 在使用 serve 和 deploy 命令时添加 --import-map <string> 标志
  • 或在 config.toml 文件中设置 import_map 属性：
1
2
[functions.my-function]import_map = "./supabase/functions/my-function/import_map.json"

从私有注册表导入

要使用私有 npm 包，请在您的函数目录中创建 .npmrc 文件。这能确保每个函数的依赖项得到适当隔离和管理。

1
2
3
4
5
6
└── supabase    └── functions        └── my-function            ├── index.ts            ├── deno.json            └── .npmrc       # 函数特定的 npm 配置

在 .npmrc 文件中添加您的注册表详细信息。请参考本指南了解更多关于 npmrc 文件语法的信息。

1
2
@myorg:registry=https://npm.registryhost.com//npm.registryhost.com/:_authToken=VALID_AUTH_TOKEN

配置好 .npmrc 后，您就可以在函数代码中导入私有包了：

1
2
3
import MyPackage from 'npm:@myorg/private-package@v1.0.1'// 使用 MyPackage

使用自定义 NPM 注册表

某些组织出于安全和合规性考虑需要使用自定义 NPM 注册表。在这种情况下，您可以通过 NPM_CONFIG_REGISTRY 环境变量指定要使用的自定义 NPM 注册表。

您可以在项目的 .env 文件中定义该变量，或者在运行部署命令时直接指定：

1
NPM_CONFIG_REGISTRY=https://custom-registry/ supabase functions deploy my-function

导入类型

如果您的开发环境已正确设置且导入的模块已导出类型，导入时将获得类型支持和自动补全功能。

某些 npm 包可能默认不包含类型定义，您可能需要从单独的包中导入它们。可以通过 @deno-types 指令指定类型：

1
2
// @deno-types="npm:@types/express@^4.17"import express from 'npm:express@^4.17'

要为内置的 Node API 包含类型定义，在导入语句顶部添加以下行：

1
/// <reference types="npm:@types/node" />