本教程基于简单的示例场景介绍如何在您的设备上中使用边缘函数 CLI 创建一个本地函数并发布该本地函数。

示例场景 #

您有一个网站，域名是 www.example.com。您在火山引擎CDN 添加了该域名。您希望通过边缘函数向用户返回自定义页面。

运行环境要求 #

运行边缘函数 CLI 的设备需要满足以下要求：

• 操作系统必须属于以下类型：
  • ARM64 macOS
  • x86-64 macOS
  • ARM64 Linux
  • x86-64 Linux
• 安装了 Node.js 和 npm。版本要求如下：
  • Node.js：8.17.0+
  • npm：6.13.4+
• 安装了 wget 或 cURL。

操作步骤 #

参见以下步骤在您的设备上使用边缘函数 CLI。

1. 安装边缘函数 CLI 并创建本地函数：使用 nest init 命令安装边缘函数 CLI 并创建一个本地函数。
2. 设置您的 Access Key ID 和 Secret Access Key：使用边缘函数 CLI 设置您的火山引擎账号的 Access Key ID 和 Secret Access Key 。
3. 编辑与调试代码：编辑和调试本地函数的代码。
4. 发布本地函数：将本地函数发布到火山引擎CDN 的全球边缘节点。
5. 关联域名并为域名配置转发规则：把函数的触发器设置为域名触发器，并在域名触发器中将函数与您的域名关联。同时为您的域名配置转发规则，当火山引擎CDN 收到匹配转发规则的用户请求时，会将用户请求转发到边缘函数。
6. 验证函数：验证函数的实际执行结果是否符合预期。

步骤一：安装边缘函数 CLI 并创建本地函数 #

在您的设备上运行以下命令。该命令会安装边缘函数 CLI，然后创建一个函数项目，并在函数项目中创建一个本地函数。

$ npx @volcengine/nest@latest init

您需要根据命令行提示，把函数名称设置为 HelloWorld，其他配置都按回车键设置为默认值。
命令运行完成后，您当前的目录结构如下：

└── 📁MyFolder
    └── 📁HelloWorld
        └── nest.json
        └── package-lock.json
        └── package.json
        └── 📁src
            └── index.js
    └── package.json

其中，HelloWorld 目录是您创建的函数项目，HelloWorld/src/index.js 是您的本地函数的入口文件。
接下来，您需要设置您的 Access Key ID 和 Secret Access Key。

步骤二：设置您的 Access Key ID 和 Secret Access Key #

在 HelloWorld 目录运行以下命令在边缘函数 CLI 中设置您的 Access Key ID 和 Secret Access Key。您可以从火山引擎控制台获取 Access Key ID 和 Secret Access Key。参考 获取 Access Key。

npx nest config set -g cloud.access_key <access_key_id>
npx nest config set -g cloud.secret_key <secret_access_key>

接下来，您可以编辑和调试本地函数的代码。

步骤三：编辑与调试代码 #

参见以下步骤编辑和调试本地函数的代码。

1. 用任意代码编辑器打开 HelloWorld/src/index.js 文件，根据需求自行修改代码。本教程使用 HelloWorld 模板提供的代码。

   说明

   代码中调用了 addEventListener() 用于注册一个事件监听器。参数中传入了 fetch 和一个回调函数 {event.respondWith(handleResponse(event));}。fetch 表示该事件监听器会监听 fetch 事件，如果 fetch 事件被域名触发器触发，则回调函数会被调用。您在步骤五会为函数配置域名触发器。

/**
 * Add the necessary event listener
 * @param {Event} fetch event, {Function} async function
 */
addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request));
})

/**
 * Make a response to client
 * @param {Request} request
 */
async function handleRequest(request) {
  return new Response('Hello World!', { status: 200 });
}

2. 在 HelloWorld 目录运行以下命令进入 Debugger 命令行对代码进行调试。在调试代码前，您需要运行 source 命令把函数代码上传到 Debugger。

$ npx nest debug
  ______    _              ______                _   _             
 |  ____|  | |            |  ____|              | | (_)            
 | |__   __| | __ _  ___  | |__ _   _ _ __   ___| |_ _  ___  _ __  
 |  __| / _` |/ _` |/ _ \ |  __| | | | '_ \ / __| __| |/ _ \| '_ \ 
 | |___| (_| | (_| |  __/ | |  | |_| | | | | (__| |_| | (_) | | | |
 |______\__,_|\__, |\___| |_|   \__,_|_| |_|\___|\__|_|\___/|_| |_|
               __/ |                                               
              |___/                                                
              
==> Setting up debugger...
==> [info]: connection setup successfully!
==> [info]: loading envrionment variables... ✓
nest:  

例如，下面的例子展示了先运行 source 把函数代码上传到 Debugger，再运行 query 触发函数代码执行。

nest: source
==> [info]: building function "HelloWorld"... 
==> Uploading functions: [HelloWorld]... 
nest: query
==> HttpResponse ✓
status: 200

statusText: OK

header:
  content-type => text/plain;charset=UTF-8
  date => Fri, 17 Jan 2025 06:07:53 GMT
  server => Sparrow
  transfer-encoding => chunked

body:
Hello World!

函数代码调试完成后，您可以发布本地函数。

步骤四：发布本地函数 #

在 HelloWorld 目录运行以下命令把本地函数发布到全球的边缘节点。您必须先将函数全量发布之后，才能将其与域名关联。

npx nest deploy --message "This is a new version"

命令行会提示您是否创建一个新的函数 ID。选择 Yes 后按回车键。边缘函数 CLI 会在边缘函数中创建一个对应的远端函数，并将该远端函数与您的本地函数同步。然后，边缘函数 CLI 会把该远端函数发布到全球的边缘节点。

$ npx nest deploy --message "This is a new version"
==> Deploying function "HelloWorld"...
✓ Function HelloWorld has no id, create a new one for it?: Yes
==> [info]: Register function on remote cloud...✓
==> [info]: Building function "HelloWorld", entry=/Users/MyFolder/HelloWorld/src/index.js ... ✓
==> [info]: function "HelloWorld" was built into /Users/MyFolder/HelloWorld/output/HelloWorld/index.js .
==> [info]: Uploading "/Users/MyFolder/HelloWorld/output/HelloWorld/index.js" to remote cloud...✓
==> [info]: Publishing function code to edge node...✓
==> [info]: Function HelloWorld publish started, the ticket is 1887
==> [info]: Loading deploy ticket status...✓
==> [info]: The Full publish now is Publishing, version is: 1.0.1
==> [info]: Run `nest tickets 1887` to get more details

==> All functions were deployed successfully.

接下来，您需要为本地函数关联域名。
函数全量发布一般需要 5 ~ 10 分钟。您必须在函数全量发布完成后才能为函数关联域名。

步骤五：关联域名并为域名配置转发规则 #

在本示例中，您使用域名触发器触发函数的执行。因此，您需要为函数关联域名www.example.com。您为域名配置转发规则后，如果火山引擎CDN 收到一个与转发规则匹配的用户请求，会把该请求转发到边缘函数。而且，域名触发器会触发函数中的 fetch 事件。
运行以下命令为本地函数关联域名www.example.com 并为域名配置转发规则。本示例不对用户请求的 URL 的路径进行限制，因此：

• 规则类型需要被设置为 --url-directory，即 URL 目录。
• 规则需要被设置为 /，表示匹配域名下的全部路径。

$ npx nest domain bind www.example.com   --url-directory /
==> [info]: Binding new domains to function...✓
==> [info]: Applying forward rules to domains...✓

您需要等待几分钟。然后在 HelloWorld 目录运行 npx nest domain list 命令查看本地函数是否已经与域名成功关联且域名触发器是否已经对该本地函数生效。

$ npx nest domain list
+---------------------------+--------+-----------+---------+------------+
|          DOMAIN           | STATUS |   TYPE    | PATTERN | IGNORECASE |
+---------------------------+--------+-----------+---------+------------+
| www.example.com           | Online | directory | /       | false      |
+---------------------------+--------+-----------+---------+------------+

当域名列表中出现了 www.example.com，且该域名的状态为 Online 时，表示域名触发器已经对该域名生效。此时，如果用户向该域名发起 HTTP 或 HTTPS 请求且该请求匹配转发规则，那么域名触发器会触发与该域名关联的函数中的 fetch 事件。
接下来，您验证函数的执行结果是否符合预期。

步骤六：验证函数 #

您可以访问 www.example.com，并验证网页的响应内容是否为 Hello World!。如果验证无误，则说明您的示例场景已实现。