Knative Functions 实战指南：用 func CLI 创建、构建与部署事件驱动函数

• 文档
• 教程
• 云原生

Knative Functions 是 Knative 面向开发者提供的一层简单编程模型，它允许你在不了解 Knative、Kubernetes、容器与 Dockerfile 细节的前提下，用funcCLI 或kn func插件轻松创建、构建和部署无状态、事件驱动的函数，并将函数以 Knative Service 的形式运行在集群上。读完本文，你将掌握函数的完整生命周期（创建 → 构建 → 本地运行 → 部署 → 调用 → 订阅 CloudEvents），理解函数模板与语言包机制，并能在本地与集群两种场景下完成函数的交付与验证。

本文的主体内容来自仓库中的 Knative Functions 概述文档，并综合 functions 目录 下的安装、创建、构建、部署、运行、调用、订阅与语言包等配套指南，以及 snippets 目录 中对应的可复用片段进行展开。

Knative Functions 的核心编程模型

Knative Functions 的设计目标是：把函数从底层基础设施中解放出来。开发者只需要聚焦业务代码本身，而不必关心 Knative、Kubernetes、容器镜像以及 Dockerfile 的具体细节（见 about-functions.md）。

这一编程模型包含几个关键事实：

• 函数即 Knative Service：通过funcCLI 创建、构建并部署的函数，最终以 Knative Service 的形式运行在集群上，天然获得 Knative Serving 提供的自动伸缩、流量管理、版本修订等能力。
• 无状态与事件驱动：Knative Functions 面向无状态（stateless）应用场景设计，函数通过 HTTP 请求或 CloudEvents 事件被触发执行。
• OCI 镜像自动生成：执行构建或部署时，CLI 会自动为函数生成一个 Open Container Initiative（OCI）格式的容器镜像，并将其推送到容器镜像仓库。每次更新代码后重新运行或部署，镜像都会随之更新。
• 双 CLI 入口：你可以使用独立的funcCLI，也可以使用 Knative CLI（kn）的kn func插件来管理函数与函数工作流，两者命令结构一致、可互换使用。

环境准备：搭建 Knative 开发环境

在使用 Knative Functions 之前，需要先有一个可用的 Knative 开发环境。官方推荐的方式是使用 Knativequickstart插件，通过该插件可以获得一个简化版的本地 Knative 安装，用于尝试 Knative Serving 与 Knative Eventing 的常用功能（参见 Knative Quickstart 教程）。

快速开始环境同时会在本地提供 Docker daemon，这直接满足后续func build、func run等命令对本地容器引擎的依赖。如果你选择在已有集群上部署，则需要自行确认集群中已安装 Knative Serving（以及订阅事件时需要的 Knative Eventing）。

安装 func CLI 与 kn func 插件

Knative Functions 的 CLI 有两种安装形态（见 install-func.md）：独立funcCLI，以及作为kn插件使用的kn-func二进制。两者的安装步骤与可选方式如下。

方式一：使用 Homebrew 安装（macOS / Linux）

brew tap knative-extensions/kn-plugins brew install func

如果你之前已经通过 Homebrew 安装了knCLI，那么安装func后它会被自动识别为kn的插件，可以等价地使用kn func或func。升级旧版本时请使用brew upgrade。

方式二：下载可执行二进制

从func的 release 页面下载对应平台的二进制（例如func_darwin_amd64或func_linux_amd64），然后重命名、赋予执行权限并放入 PATH：

mv <path-to-binary-file> func chmod +x func mv func /usr/local/bin

最后用func version验证 CLI 是否可用。

方式三：从源码构建（Go）

git clone https://github.com/knative/func.git func cd func/ make

构建完成后将func放入系统 PATH，并用func version验证。

方式四：以容器镜像方式运行

docker run --rm -it ghcr.io/knative/func/func create -l node -t http myfunc

需要注意的是，容器方式运行不会把二进制放到持久路径上，每次使用都需要重复执行该命令。

安装 kn func 插件

若要以插件形式使用，下载 release 二进制后将其重命名为kn-func，赋予执行权限并放入 PATH：

mv <path-to-binary-file> kn-func chmod +x kn-func mv kn-func /usr/local/bin

验证命令为kn func version（详见 install-kn-func-plugin.md）。

函数模板：语言与调用格式的选择

Knative Functions 提供了开箱即用的函数模板（见 functions-templates-intro.md）。当你执行create命令时，CLI 会基于所选模板生成一个函数项目的基础脚手架（boilerplate），模板决定了函数使用的语言与调用格式。

目前支持的模板语言包括：

• Node.js
• Python
• Go
• Quarkus（Java 生态）
• Rust
• Spring Boot（Java 生态）
• TypeScript

每种模板都同时支持两种调用格式：CloudEvent与HTTP。你可以根据函数将被 HTTP 请求触发还是被事件触发来选择相应的模板，这一选择会直接影响生成的项目骨架中入口函数的签名形态。

创建函数项目

安装完成后，即可通过func create或kn func create创建函数项目（见 create-a-function.md）：

func create -l <language> <function-name>

例如创建一个 Go 语言函数：

func create -l go hello

等价地使用kn插件：

kn func create -l go hello

命令执行成功后，会在当前目录下生成一个名为hello的函数项目，控制台输出Created go function in hello。项目内部包含由模板生成的入口源码、func.yaml配置以及构建所需的辅助文件，之后的构建、运行、部署命令都应在此项目目录内执行。

构建函数：生成本地容器镜像

build命令用于为函数生成 OCI 容器镜像并推送到镜像仓库，但它不会运行或部署函数。这在"只构建镜像、暂不部署"的测试场景中非常有用（见 build-func-intro.md）。

在项目目录内执行：

func build

或：

kn func build

构建时，CLI 会使用项目名称与镜像仓库名称拼接出函数的完整镜像名。如果项目此前从未构建过，CLI 会提示你输入image registry（镜像仓库地址）。仓库坐标也可以通过环境变量FUNC_REGISTRY预先配置，从而跳过交互式提示。

对于需要认证的私有镜像仓库，可以通过环境变量注入凭据：

• FUNC_USERNAME：镜像仓库认证用户名
• FUNC_PASSWORD：镜像仓库认证密码

这两个环境变量对所有 builder（host、s2i、pack）均生效。相比在命令行中直接使用--password参数，使用环境变量更安全——命令行参数会通过ps被系统上所有用户看到（见 proc-building-function.md）。

本地运行函数

run命令会在你的本地环境中运行函数：如果镜像尚未构建，它会先构建镜像，然后在本地启动容器运行，但不部署到集群，适合本地测试（见 run-func-intro.md）。

在项目目录内执行：

cd hello func run [--registry <registry>]

或使用kn func：

kn func run [--registry <registry>]

行为细节说明：

• 首次运行时，如果没有构建过镜像，必须通过--registry提供镜像仓库地址（同样可用FUNC_REGISTRY环境变量替代）。
• 该命令按需自动构建镜像。
• 强制重新构建镜像：func run --build
• 跳过构建直接运行：func run --build=false

运行成功后，可用func invoke验证函数是否正常工作。

部署函数到集群

deploy命令完成两件事：为函数生成 OCI 容器镜像并推送到镜像仓库，然后将函数作为Knative Service部署到集群（见 deploy-func-intro.md）。重新部署会更新容器镜像及集群上正在运行的 Service，已部署的函数在集群上的访问方式与任何其他 Knative Service 相同。

标准部署

在项目目录内执行：

func deploy --registry <registry>

或：

kn func deploy --registry <registry>

部署时，CLI 以函数项目名称作为 Knative Service 名称，并用项目名与镜像仓库名拼接出完整的镜像名。预期输出类似：

🙌 Function image built: <registry>/hello:latest ✅ Function deployed in namespace "default" and exposed at URL: http://hello.default.127.0.0.1.sslip.io

使用 raw deployer 部署为原生 Kubernetes 资源

如果希望函数以原生 Kubernetes Deployment 和 Service 的形式部署，而不是 Knative Service，可以指定rawdeployer：

func deploy --registry <registry> --deployer raw

kn func deploy --registry <registry> --deployer raw

在集群上远程构建

如果你本地没有 Docker daemon，或正处于 CI/CD 流水线中，可以使用func deploy --remote在集群上完成构建（见 building-functions.md）。首次执行时需要同时指定 Git 仓库地址：

func deploy --remote --registry <registry> --git-url <git-url> -p hello

kn func deploy --remote --registry <registry> --git-url <git-url> -p hello

指定过一次 Git URL 后，后续命令可以省略该参数。注意：如果是直传式部署（源码在本地而非 Git 仓库），仍可进行集群构建且无需 Git URL；但若此前已指定过 Git URL，需要显式将其置空：func deploy --remote --git-url=""。远程构建的前提是函数存在于 Git 仓库中，且集群已配置 Tekton Pipelines。

私有镜像仓库的认证方式与构建阶段一致，通过FUNC_USERNAME与FUNC_PASSWORD环境变量注入，对所有 builder 生效。

调用函数进行验证

func invoke命令用于向函数发送测试请求，可以验证函数在本机或集群上是否正常工作、能否正确接收 HTTP 请求与 CloudEvents（见 invoking-functions.md）。

• 若函数在本地运行，func invoke会把测试请求发送到本地实例。
• 可以使用--data参数携带测试数据，并通过其他选项模拟不同类型的请求。

部署或运行成功后执行：

func invoke

kn func invoke

预期输出会打印收到的 HTTP 请求头与正文，例如：

Received response POST / HTTP/1.1 hello.default.127.0.0.1.sslip.io User-Agent: Go-http-client/1.1 Content-Length: 25 Accept-Encoding: gzip Content-Type: application/json K-Proxy-Request: activator X-Request-Id: 9e351834-0542-4f32-9928-3a5d6aece30c Forwarded: for=10.244.0.15;proto=http X-Forwarded-For: 10.244.0.15, 10.244.0.9 X-Forwarded-Proto: http Body:

其中的K-Proxy-Request: activator头表明请求确实经由 Knative 的 activator 组件代理转发，是函数作为 Knative Service 运行的有力佐证。

订阅 CloudEvents：让函数响应事件

Knative Functions 可以订阅来自 Knative Broker 的事件。subscribe命令会把函数连接到一组匹配特定 CloudEvent 元数据过滤条件的事件，并以 Knative Broker 作为事件来源进行消费（见 proc-subscribe-function.md）。前置条件是集群上已安装 Knative Eventing。

订阅指定 Broker 的事件：

func subscribe --filter type=com.example --filter extension=my-extension-value --source my-broker

kn func subscribe --filter type=com.example --filter extension=my-extension-value --source my-broker

订阅默认 Broker 的事件（省略--source）：

func subscribe --filter type=com.example --filter extension=my-extension-value

kn func subscribe --filter type=com.example --filter extension=my-extension-value

--filter参数可多次指定，用于匹配 CloudEvent 的type、扩展属性等元数据；--source指定作为事件来源的 Broker 名称。

部署时自动创建 Triggers

除了手动执行subscribe，当你在项目目录内执行func deploy时，CLI 会自动为函数创建 Knative Triggers（见 subscribing-functions.md）：

func deploy

kn func deploy

预期输出中会包含创建 Triggers 的日志：

🙌 Function image built: <registry>/hello:latest 🎯 Creating Triggers on the cluster ✅ Function deployed in namespace "default" and exposed at URL: http://hello.default.127.0.0.1.sslip.io

这使得函数从部署之初就具备接收事件的能力，事件驱动的落地更加直接。

语言包：扩展函数运行时能力

语言包（Language Packs）用于将 Knative Functions 扩展到更多运行时、函数签名、操作系统及工具链。语言包通过 Git 仓库或本地磁盘目录分发（见 language-packs.md）。

使用外部 Git 仓库作为模板源

创建新函数时，可以指定一个 Git 仓库作为模板文件的来源。例如使用 Knative Extensions 维护的func-tastic示例模板仓库中的metacontroller模板创建 Node.js 函数：

func create myfunc -l nodejs -t metacontroller --repository https://github.com/knative-extensions/func-tastic

本地安装语言包

也可以使用func repository命令把语言包安装到本地。例如添加 Knative Extensions 示例模板仓库：

func repository add knative https://github.com/knative-extensions/func-tastic

安装之后，在create命令中通过knative前缀引用该仓库内的模板：

func create -t knative/metacontroller -l nodejs my-controller-function

这种"仓库 + 前缀"的机制，让团队可以将自定义模板沉淀为共享语言包，在组织内复用统一的函数骨架与工具链。

进一步探索

• 函数创建、构建、部署、运行、调用、订阅各环节的完整命令与前置条件，可分别参考 creating-functions.md、building-functions.md、deploying-functions.md、running-functions.md、invoking-functions.md 与 subscribing-functions.md。
• 语言包的扩展契约与仓库管理细节，见 language-packs.md。
• 若想快速体验完整流程，可跟随 Knative Quickstart 教程 搭建本地开发环境后按本文步骤实践。

从创建项目到订阅事件，Knative Functions 把"编写函数 → 构建镜像 → 部署服务 → 接入事件"整条链路压缩为少数几条 CLI 命令，是 Knative 平台上低门槛的函数式开发入口，也是事件驱动应用与服务网格化部署之间的一座便捷桥梁。

• 文档
• 教程
• 云原生