山维空间
·
Cloudflare Worker + Next.js 使用环境变量最佳实践（2026终极版）
内容提要
本文探讨了在 Cloudflare Worker 和 Next.js 中使用环境变量的最佳实践，强调构建时与运行时的区别。建议以“NEXT_PUBLIC_”开头配置构建时变量，并通过 wrangler.jsonc 管理服务端变量。还介绍了本地开发时使用 .dev.vars 文件的重要性，以及确保类型安全和环境隔离的方法，以避免常见错误。
关键要点
-
在 Cloudflare Worker 和 Next.js 中，环境变量的配置分为构建时和运行时。
-
构建时变量需以 'NEXT_PUBLIC_' 开头，并在构建时环境变量中配置，以确保在编译时被正确注入。
-
运行时变量通过 wrangler.jsonc 管理，服务端代码可以访问这些变量。
-
本地开发时，使用 .dev.vars 文件来注入敏感信息，避免将其提交到版本控制系统。
-
确保类型安全，使用 Cloudflare 提供的工具生成类型定义，以便在代码中获得自动补全。
-
环境变量的配置应完全复制到每个环境，避免隐式继承带来的问题。
-
敏感信息应通过 wrangler secret put 上传，确保安全管理。
延伸解读
构建时与运行时的区别
在 Cloudflare Worker 和 Next.js 中，环境变量的配置分为构建时和运行时。构建时变量需要在构建阶段就定义好，以确保在编译时被正确注入，而运行时变量则是在服务端运行时动态获取。理解这两者的区别对于避免常见错误至关重要。
敏感信息的安全管理
文章强调了敏感信息的管理，建议使用 wrangler secret put 上传敏感数据，避免在代码中明文出现。此外，本地开发时应使用 .dev.vars 文件来注入敏感信息，确保这些信息不会被提交到版本控制系统中。
环境变量的完全复制
在配置环境变量时，文章指出每个环境的配置应完全复制，避免隐式继承带来的问题。这种做法虽然显得冗余，但能确保配置的确定性，减少潜在的错误和不一致性。
延伸问答
在 Cloudflare Worker 和 Next.js 中，如何配置构建时环境变量？
构建时环境变量需以 'NEXT_PUBLIC_' 开头，并在构建时环境变量中配置，以确保在编译时被正确注入。
如何管理 Cloudflare Worker 的运行时环境变量？
运行时变量通过 wrangler.jsonc 管理，服务端代码可以访问这些变量。
本地开发时如何安全地使用敏感信息？
使用 .dev.vars 文件来注入敏感信息，避免将其提交到版本控制系统。
为什么构建时和运行时的环境变量需要分开处理？
构建时和运行时的环境变量有不同的作用，构建时变量在编译时被注入，而运行时变量在服务端代码执行时使用。
如何确保在 Cloudflare Worker 中的环境变量类型安全？
使用 Cloudflare 提供的工具生成类型定义，以便在代码中获得自动补全。
在 Cloudflare Worker 中如何安全管理敏感信息？
敏感信息应通过 wrangler secret put 上传，确保安全管理。
