Next.js Edge 运行时中集成 LaunchDarkly 特性开关基于 Global Config 的近即时读取实战【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples本篇技术指南围绕仓库中的 edge-middleware/feature-flag-launchdarkly 示例展开讲解如何通过 Vercel Marketplace 的 LaunchDarkly 官方集成把 LaunchDarkly 的特性开关Feature Flag同步进 Vercel Global Config并在 Next.js Edge 运行时中读取。读完本文你将掌握该示例的完整配置步骤、环境变量体系、Edge Runtime 下客户端实例的缓存技巧以及如何在自己的应用中复现这套近即时near-instant的标志读取方案。示例背景为什么要把 LaunchDarkly 标志同步进 Global Config传统的特性开关 SDK 需要客户端启动时向远端服务拉取标志定义或依赖长轮询/流式连接维持更新这在无服务器Serverless和边缘Edge环境下会带来额外的网络延迟与冷启动开销。本示例的核心思路是借助 Vercel Marketplace 上的 LaunchDarkly 集成让 LaunchDarkly 把特性标志自动同步到 Vercel 的 Global Config 中应用端直接以极低延迟从 Global Config 读取标志值从而实现近即时的标志切换生效。该思路在同一仓库的多个示例中反复出现feature-flag-split通过vercel/global-config的createClient读取 Split 的标志定义feature-flag-hypertune用 Global Config 作为 Hypertune 的初始化数据源feature-flag-apple-store更是直接用createClientget读取存于 Global Config 的布尔标志。而本示例的特殊之处在于它不是应用直接读 Global Config 键值而是让 LaunchDarkly 官方 SDK 与 Global Config 客户端配合通过launchdarkly/vercel-server-sdk完成标志评估。环境变量体系集成安装后获得的两个关键变量安装集成后Vercel 会自动为项目注入以下环境变量环境变量来源作用NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_IDLaunchDarkly 集成自动注入你在 LaunchDarkly 控制台中的客户端侧 IDClient-Side ID用于初始化 SDKEXPERIMENTATION_CONFIG开启 Global Config 同步后自动注入Global Config 的连接字符串示例用它创建 Global Config 客户端其中EXPERIMENTATION_CONFIG的注入有一个前提条件在 Vercel Marketplace 安装 LaunchDarkly 集成时必须在 Configuration and Plan 步骤中打开 Enable Global Config Syncing 开关见 README。开启后Vercel 会为你预置一个 Global Config并把其连接字符串暴露为EXPERIMENTATION_CONFIG环境变量。从仓库的 package.json 可以看到示例依赖了两个关键库launchdarkly/vercel-server-sdkv1.3.x提供服务端 SDK 的init与variation和vercel/global-configv1.5.x提供createClient。第一步在 LaunchDarkly 控制台创建特性开关在 LaunchDarkly Console 中于你的客户端侧 ID 所属的**同一个项目Project和环境Environment**下创建本示例所使用的特性开关标志名称My Flag类型布尔值booleanKeymy-flag变体variationstrue和false创建后把标志打开ON。README 明确指出切换 Targeting定向投放的开关页面显示的内容就会随之变化从而验证标志确实是从 Global Config 读取的。关于 Context上下文的关键说明示例在评估标志时使用了一个kind为org、key为my-org-key的上下文见下文源码分析。README 特别强调Context 无需提前在 LaunchDarkly 中创建应用在评估时直接发送即可默认的定向规则无需任何额外配置即可生效若你要添加定向规则应定向到org这个 context kind而不是默认的user。第二步核心源码逐行解析示例的业务代码全部集中在 app/page.tsx我们先看它的客户端初始化逻辑const getLdClient cache(async (): PromiseLDClient { const edgeConfigClient createClient(process.env.EXPERIMENTATION_CONFIG) const ldClient init( process.env.NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID!, edgeConfigClient ) await ldClient.waitForInitialization() return ldClient })这段代码完成了三件事创建 Global Config 客户端createClient(process.env.EXPERIMENTATION_CONFIG)使用集成注入的连接字符串初始化 Global Config 客户端作为 LaunchDarkly SDK 的底层数据源初始化 LaunchDarkly SDKinit接收客户端侧 ID 和 Global Config 客户端SDK 将从 Global Config 中读取已同步的标志定义等待初始化完成await ldClient.waitForInitialization()确保在首次评估前 SDK 已就绪。随后在页面组件中评估标志const ldContext { kind: org, key: my-org-key, someAttribute: my-attribute-value, } const flagValue await ldClient.variation(my-flag, ldContext, true)variation(my-flag, ldContext, true)的第三个参数true是默认值当标志不存在或无法评估时返回true。页面据此渲染Flag is on/off并显示加载耗时Loading flag took 1ms或实际毫秒数用于直观展示 Global Config 的近即时读取优势。Edge Runtime 下的客户端复用陷阱page.tsx顶部声明了export const runtime edge与export const dynamic force-dynamic使页面在 Edge Runtime 中按请求动态渲染。源码注释中有一段非常值得注意的工程经验Edge Runtime 无法跨请求共享 PromisewaitForInitialization会尝试复用已存在的 pending promise若直接缓存一个全局客户端后续请求可能读到前一个请求创建的 promise因此每个请求都应创建新的客户端实例防止跨请求读到过期 promise但同一请求内仍希望复用客户端让多个组件调用getLdClient()拿到同一个实例于是用 React 的cache()包裹cache()在每次服务器请求后重置因此下一个请求会获得全新的 LaunchDarkly 客户端实例。注释还额外提醒了两点使用前提这套cache()方案仅对 Edge Functions 必要Serverless Functions 无需如此处理而在Edge Middleware中使用 LaunchDarkly 客户端时由于cache()在 Middleware 中不生效必须为每个请求创建全新实例。第三步本地运行与云端部署方式一一键部署点击 Vercel 的 Deploy 按钮见 README按向导完成 LaunchDarkly 集成安装并开启 Global Config 同步即可。仓库中的 components/deploy-button.tsx 封装了带repository-url、project-name等参数的克隆部署按钮页面右上角的部署入口即由此渲染。方式二克隆到本地使用create-next-app引导示例项目推荐 pnpmpnpm create next-app --example https://github.com/vercel/examples/tree/main/edge-middleware/feature-flag-launchdarkly然后启动开发模式pnpm dev启动前需要确保项目中已配置NEXT_PUBLIC_LAUNCHDARKLY_CLIENT_SIDE_ID与EXPERIMENTATION_CONFIG两个环境变量本地可通过.env.local配置云端由集成自动注入。生产构建与启动对应 package.json 中的build、start脚本。与其他特性开关示例的对照同一仓库的edge-middleware目录下还有多个特性开关示例可作为横向参考feature-flag-split通过vercel/global-config的createClient(process.env.GLOBAL_CONFIG)创建客户端再以PluggableStorageEdgeConfigWrapper让 Split SDK 从 Global Config 读取标志定义feature-flag-hypertune以createClient(process.env.GLOBAL_CONFIG)为数据源通过VercelEdgeConfigInitDataProvider把 Global Config 作为 Hypertune 的初始化数据提供者feature-flag-apple-store更直接地使用createClientedgeConfig.getFeatureFlags(key)读取布尔标志并在 lib/feature-flags.ts 中用前缀featureFlagsAppleStore_避免键名冲突。可以看到本示例与它们共享Global Config 作为标志存储层的架构理念但评估动作仍由 LaunchDarkly 官方 SDK 完成保留了 LaunchDarkly 的定向规则、上下文评估等完整能力。使用限制与注意事项综合 README 与源码使用本方案时有几点需要留意必须开启 Global Config Syncing未打开该开关则不会注入EXPERIMENTATION_CONFIGcreateClient将收到空值标志需在客户端侧 ID 对应的项目/环境中创建跨项目或跨环境的标志不会出现在该 Global Config 的同步数据中Edge 环境实例管理Edge Functions 需按请求重建客户端借助cache()在请求内复用Edge Middleware 则必须每次新建实例默认值兜底variation的默认参数保证了标志缺失或同步未完成时应用仍可正常工作示例本身是演示性质生产环境应结合自身权限体系评估是否在页面直接注入NEXT_PUBLIC_前缀的客户端 ID。掌握以上要点后你就可以把 LaunchDarkly 的特性开关能力与 Vercel Global Config 的近即时读取结合起来在边缘节点上构建低延迟、可秒级切换的功能发布体系。【免费下载链接】examplesEnjoy our curated collection of examples and solutions. Use these patterns to build your own robust and scalable applications.项目地址: https://gitcode.com/GitHub_Trending/examples1/examples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
