Coze Studio Rspack 项目模板环境变量体系全解析多环境配置与 dts 类型自动生成【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studioCoze Studiocoze-studio仓库内置了common/_templates/rspack-web前端项目初始化模板其环境变量管理采用单一配置文件 构建期注入 类型声明自动生成的组合方案所有环境变量统一收敛在 env/index.ts 中按多环境地区分别取值构建时通过DefinePlugin注入到业务代码同时由脚本自动生成 src/typing/env/index.d.ts 类型声明让开发者在全项目范围内获得完整的类型提示与编译期校验。本文将以模板自带的 env/README.md 为主线结合仓库源码完整讲解这套环境变量机制的设计约定、底层实现与实战操作。一、配置入口一切环境变量都收敛于 env/index.ts模板的环境变量体系遵循单一事实来源Single Source of Truth原则。所有环境变量都定义在 env/index.ts 中该文件同时承担两个职责从process.env读取系统注入的原始环境变量归一化后导出统一的envs对象供构建配置与业务代码使用。模板预置了四组基础环境变量其完整定义与含义如下表变量名取值逻辑含义IS_DEV_MODENODE_ENV development是否本地开发环境local environmentIS_PRODUCT_MODENODE_ENV production是否生产环境production environmentIS_CIprocess.env.CI true是否 CI 构建流水线IS_SCM!!process.env.BUILD_PATH_SCM是否走 SCM静态资源托管/CDN部署链路源码摘录env/index.tsconst { NODE_ENV } process.env; const IS_DEV_MODE NODE_ENV development; // local environment const IS_PRODUCT_MODE NODE_ENV production; // production environment const IS_CI process.env.CI true; const IS_SCM !!process.env.BUILD_PATH_SCM; export const envs { IS_DEV_MODE, IS_PRODUCT_MODE, IS_CI, IS_SCM, };从源码结构可以看出两个设计要点显式归一化而非透传原始环境变量是字符串模板在这里统一转换为boolean语义如CI true、!!BUILD_PATH_SCM避免业务侧反复做字符串比较多环境地区扩展点README 指出可根据多环境地区的环境变量可分别设置相关变量即不同部署环境或地区在启动/构建时注入不同的NODE_ENV、CI、BUILD_PATH_SCM等原始值env/index.ts负责将它们归一化为统一的布尔语义业务代码无需感知环境差异。空值兜底校验模板还在文件末尾提供了防御性校验env/index.tsconst emptyVars Object.entries({ ...envs, }).filter(([key, value]) value undefined); if (emptyVars.length) { throw Error(以下环境变量值为空${emptyVars.join(、)}); }若envs中任何一项的值为undefined构建过程会直接抛出异常并列出缺失变量名避免环境变量缺失但构建静默成功、运行时行为异常的隐性故障。当前四个预置变量均恒为布尔值不会触发该校验它是为后续新增的可能为undefined的变量准备的保险机制。二、构建期注入DefinePlugin 将 envs 注入全局环境变量定义之后需要让构建配置与业务代码都能读到。模板在 rspack.config.ts 中完成两件关键工作。2.1 消费 envs 驱动构建行为配置文件顶部引入envs并根据其值决定构建参数rspack.config.tsimport { updateDTS } from ./env/scripts/index; import { envs } from ./env; const { IS_DEV_MODE, IS_CI, IS_SCM } envs; const CDN_PATH IS_SCM ? //${process.env.CDN_INNER_CN}/${process.env.CDN_PATH_PREFIX} : /; if (IS_DEV_MODE) { updateDTS(); } const config: Configuration { mode: IS_DEV_MODE ? development : production, ... output: { path: output, publicPath: CDN_PATH }, ... builtins: { treeShaking: !IS_DEV_MODE !IS_CI, },具体联动关系IS_SCM决定output.publicPath走 SCM 链路时使用 CDN 域名前缀由CDN_INNER_CN、CDN_PATH_PREFIX两个附加环境变量拼出否则回退为根路径/IS_DEV_MODE决定 Rspack 的modedevelopment/production、swc-loader 的 React 开发模式与热刷新runtime: automatic、refresh: IS_DEV_MODEIS_CI与IS_DEV_MODE共同决定是否开启 tree shakingCI 下关闭以保证产物可排查并影响构建stats输出详略。2.2 DefinePlugin 全局注入配置通过DefinePlugin将envs的全部键值展开为编译期全局常量rspack.config.tsplugins: [ new rspack.DefinePlugin({ ...envs, }), ... ]这意味着IS_DEV_MODE等标识在业务代码中可以直接作为全局变量使用并在编译期被替换为真实布尔字面量——无运行期读取开销且死代码可被 tree shaking 消除。2.3 业务侧使用示例模板自身就是这套机制的示范用例。在 src/store/store.ts 中Zustand 的 devtools 中间件以IS_DEV_MODE作为启用开关export const useStore createUserInfoSlice()( devtools( (...a) ({ ...createUserInfoSlice(...a), }), { enabled: IS_DEV_MODE, name: api-builder/app, }, ), );这里的IS_DEV_MODE之所以能通过 TypeScript 编译正是因为下面要讲的 dts 自动生成约定提供了全局类型声明。三、dts 自动生成约定类型声明永不手写这是 env/README.md 最核心的约定原文要点如下src/typings/env/index.d.ts由脚本自动更新禁止手动修改类型来源为env/index.ts中的envs变量新增环境变量时必须确保其作为envs的一组 key-value 加入。3.1 生成脚本的底层实现自动更新脚本位于 env/scripts/index.ts核心函数updateDTS基于 ts-morph 对 TypeScript 源码做 AST 解析流程如下初始化 ts-morph 工程开启strictNullChecks、incremental等编译选项加载 env/index.ts 为源文件定位envs变量通过getVariableDeclarationOrThrow(envVarName)获取名为envs的变量声明默认参数envVarName envs并通过getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression)确保初始值是对象字面量遍历对象属性对普通属性PropertyAssignment、简写属性ShorthandPropertyAssignment直接取其类型文本对展开属性SpreadAssignment则先取表达式类型若是对象类型再递归展开其属性——这意味着envs中即使使用...展开其他对象其成员也会被完整纳入类型声明生成声明文件在目标路径src/typing/env/index.d.ts创建新文件overwrite: true写入// 基于env/index.ts自动生成请勿手动修改的版权/来源注释再将所有属性按名称排序后输出为带declare const的全局声明同步落盘typeDefs.saveSync()保存文件并在控制台打印生成耗时DTS generated in xx ms。3.2 触发时机updateDTS并非每次构建都执行。查看 rspack.config.tsif (IS_DEV_MODE) { updateDTS(); }即仅在本地开发模式NODE_ENVdevelopment下自动刷新类型声明保证开发者新增环境变量后无需手动跑任何命令即可获得最新类型生产/CI 构建则直接复用已生成好的声明文件避免构建链路出现写文件副作用。3.3 生成产物示例模板仓库中已包含一次生成的成果 src/typing/env/index.d.ts// Automatically generated based on env/index.ts, do not modify manually declare const IS_CI: boolean; declare const IS_DEV_MODE: boolean; declare const IS_PRODUCT_MODE: boolean; declare const IS_SCM: boolean;可以看到声明按变量名排序类型信息此处均为boolean直接取自envs各属性的静态类型。这份文件与 src/typing/global.d.ts声明*.svg、*.png、*.less等模块类型共同构成模板的全局类型层业务代码无需任何 import 即可使用这些全局标识。四、新增一个环境变量的完整操作流程基于上述机制在模板中新增环境变量的标准操作只需两步第一步在 env/index.ts 中读取原始值并加入envsconst IS_FEATURE_X process.env.FEATURE_X true; export const envs { IS_DEV_MODE, IS_PRODUCT_MODE, IS_CI, IS_SCM, IS_FEATURE_X, // 新增项作为 envs 的一组 key-value };第二步本地开发启动自动刷新类型声明执行rushx dev等价于NODE_ENVdevelopment rspack serve见 package.json 的 scripts 定义开发模式下的updateDTS()会自动把IS_FEATURE_X: boolean追加进 src/typing/env/index.d.ts随后即可在任意业务代码中直接使用IS_FEATURE_X并获得完整的类型提示。注意两点约定务必作为envs的成员加入仅定义在文件顶层而未放入envs的变量不会被脚本识别不要手动编辑src/typing/env/index.d.ts改动会在下次开发启动时被覆盖若希望新变量立即可用而暂时不便重启可自行在本地临时执行一次updateDTS脚本。五、多环境地区差异化配置的落地方式README 明确提出可根据多环境地区的环境变量可分别设置相关变量。结合模板的实现差异化的注入点是构建/启动时的进程环境本地开发NODE_ENVdevelopment→IS_DEV_MODE true生产构建NODE_ENVproduction→IS_PRODUCT_MODE trueCI 流水线设置CItrue→IS_CI true同时可按需关闭 tree shaking、输出更详细的 statsSCM/CDN 部署设置BUILD_PATH_SCM及CDN_INNER_CN、CDN_PATH_PREFIX→IS_SCM truepublicPath自动切换为 CDN 地址。不同地区或环境只需在各自的部署配置中注入不同的原始环境变量值业务代码与构建配置均无需修改这正是单一配置入口 归一化语义设计带来的扩展性。六、验证与调试启动开发rushx dev控制台会打印DTS generated in xx ms表示类型声明已刷新同时验证 src/typing/env/index.d.ts 的内容生产构建rushx build等价于NODE_ENVproduction rspack build可观察IS_PRODUCT_MODE分支下的构建行为缺失值排查若后续新增变量在构建期取到undefined构建会直接失败并抛出以下环境变量值为空的异常按提示补全对应环境变量即可。更完整的模板能力React Router、semi 组件库、less/tailwind、vitest 测试、slardar SDK 等可参阅模板根目录的 README.md而环境变量机制本身遵循的正是本模板与 rsbuild-web 等其他子模板共用的配置收敛 类型自动生成工程化范式。七、总结Coze Studio 的 rspack-web 模板通过 env/index.ts配置单一入口、rspack.config.tsDefinePlugin注入 构建行为联动、env/scripts/index.tsts-morph 自动生成类型声明三层结构实现了多环境变量管理的完整闭环新增变量只需改动一处类型提示自动生效构建行为随环境自动切换缺失配置在构建期即被拦截。这套约定对任何基于 Rspack 的前端工程都具有直接的复用价值。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Coze Studio Rspack 项目模板环境变量体系全解析：多环境配置与 dts 类型自动生成
Coze Studio Rspack 项目模板环境变量体系全解析多环境配置与 dts 类型自动生成【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studioCoze Studiocoze-studio仓库内置了common/_templates/rspack-web前端项目初始化模板其环境变量管理采用单一配置文件 构建期注入 类型声明自动生成的组合方案所有环境变量统一收敛在 env/index.ts 中按多环境地区分别取值构建时通过DefinePlugin注入到业务代码同时由脚本自动生成 src/typing/env/index.d.ts 类型声明让开发者在全项目范围内获得完整的类型提示与编译期校验。本文将以模板自带的 env/README.md 为主线结合仓库源码完整讲解这套环境变量机制的设计约定、底层实现与实战操作。一、配置入口一切环境变量都收敛于 env/index.ts模板的环境变量体系遵循单一事实来源Single Source of Truth原则。所有环境变量都定义在 env/index.ts 中该文件同时承担两个职责从process.env读取系统注入的原始环境变量归一化后导出统一的envs对象供构建配置与业务代码使用。模板预置了四组基础环境变量其完整定义与含义如下表变量名取值逻辑含义IS_DEV_MODENODE_ENV development是否本地开发环境local environmentIS_PRODUCT_MODENODE_ENV production是否生产环境production environmentIS_CIprocess.env.CI true是否 CI 构建流水线IS_SCM!!process.env.BUILD_PATH_SCM是否走 SCM静态资源托管/CDN部署链路源码摘录env/index.tsconst { NODE_ENV } process.env; const IS_DEV_MODE NODE_ENV development; // local environment const IS_PRODUCT_MODE NODE_ENV production; // production environment const IS_CI process.env.CI true; const IS_SCM !!process.env.BUILD_PATH_SCM; export const envs { IS_DEV_MODE, IS_PRODUCT_MODE, IS_CI, IS_SCM, };从源码结构可以看出两个设计要点显式归一化而非透传原始环境变量是字符串模板在这里统一转换为boolean语义如CI true、!!BUILD_PATH_SCM避免业务侧反复做字符串比较多环境地区扩展点README 指出可根据多环境地区的环境变量可分别设置相关变量即不同部署环境或地区在启动/构建时注入不同的NODE_ENV、CI、BUILD_PATH_SCM等原始值env/index.ts负责将它们归一化为统一的布尔语义业务代码无需感知环境差异。空值兜底校验模板还在文件末尾提供了防御性校验env/index.tsconst emptyVars Object.entries({ ...envs, }).filter(([key, value]) value undefined); if (emptyVars.length) { throw Error(以下环境变量值为空${emptyVars.join(、)}); }若envs中任何一项的值为undefined构建过程会直接抛出异常并列出缺失变量名避免环境变量缺失但构建静默成功、运行时行为异常的隐性故障。当前四个预置变量均恒为布尔值不会触发该校验它是为后续新增的可能为undefined的变量准备的保险机制。二、构建期注入DefinePlugin 将 envs 注入全局环境变量定义之后需要让构建配置与业务代码都能读到。模板在 rspack.config.ts 中完成两件关键工作。2.1 消费 envs 驱动构建行为配置文件顶部引入envs并根据其值决定构建参数rspack.config.tsimport { updateDTS } from ./env/scripts/index; import { envs } from ./env; const { IS_DEV_MODE, IS_CI, IS_SCM } envs; const CDN_PATH IS_SCM ? //${process.env.CDN_INNER_CN}/${process.env.CDN_PATH_PREFIX} : /; if (IS_DEV_MODE) { updateDTS(); } const config: Configuration { mode: IS_DEV_MODE ? development : production, ... output: { path: output, publicPath: CDN_PATH }, ... builtins: { treeShaking: !IS_DEV_MODE !IS_CI, },具体联动关系IS_SCM决定output.publicPath走 SCM 链路时使用 CDN 域名前缀由CDN_INNER_CN、CDN_PATH_PREFIX两个附加环境变量拼出否则回退为根路径/IS_DEV_MODE决定 Rspack 的modedevelopment/production、swc-loader 的 React 开发模式与热刷新runtime: automatic、refresh: IS_DEV_MODEIS_CI与IS_DEV_MODE共同决定是否开启 tree shakingCI 下关闭以保证产物可排查并影响构建stats输出详略。2.2 DefinePlugin 全局注入配置通过DefinePlugin将envs的全部键值展开为编译期全局常量rspack.config.tsplugins: [ new rspack.DefinePlugin({ ...envs, }), ... ]这意味着IS_DEV_MODE等标识在业务代码中可以直接作为全局变量使用并在编译期被替换为真实布尔字面量——无运行期读取开销且死代码可被 tree shaking 消除。2.3 业务侧使用示例模板自身就是这套机制的示范用例。在 src/store/store.ts 中Zustand 的 devtools 中间件以IS_DEV_MODE作为启用开关export const useStore createUserInfoSlice()( devtools( (...a) ({ ...createUserInfoSlice(...a), }), { enabled: IS_DEV_MODE, name: api-builder/app, }, ), );这里的IS_DEV_MODE之所以能通过 TypeScript 编译正是因为下面要讲的 dts 自动生成约定提供了全局类型声明。三、dts 自动生成约定类型声明永不手写这是 env/README.md 最核心的约定原文要点如下src/typings/env/index.d.ts由脚本自动更新禁止手动修改类型来源为env/index.ts中的envs变量新增环境变量时必须确保其作为envs的一组 key-value 加入。3.1 生成脚本的底层实现自动更新脚本位于 env/scripts/index.ts核心函数updateDTS基于 ts-morph 对 TypeScript 源码做 AST 解析流程如下初始化 ts-morph 工程开启strictNullChecks、incremental等编译选项加载 env/index.ts 为源文件定位envs变量通过getVariableDeclarationOrThrow(envVarName)获取名为envs的变量声明默认参数envVarName envs并通过getInitializerIfKindOrThrow(SyntaxKind.ObjectLiteralExpression)确保初始值是对象字面量遍历对象属性对普通属性PropertyAssignment、简写属性ShorthandPropertyAssignment直接取其类型文本对展开属性SpreadAssignment则先取表达式类型若是对象类型再递归展开其属性——这意味着envs中即使使用...展开其他对象其成员也会被完整纳入类型声明生成声明文件在目标路径src/typing/env/index.d.ts创建新文件overwrite: true写入// 基于env/index.ts自动生成请勿手动修改的版权/来源注释再将所有属性按名称排序后输出为带declare const的全局声明同步落盘typeDefs.saveSync()保存文件并在控制台打印生成耗时DTS generated in xx ms。3.2 触发时机updateDTS并非每次构建都执行。查看 rspack.config.tsif (IS_DEV_MODE) { updateDTS(); }即仅在本地开发模式NODE_ENVdevelopment下自动刷新类型声明保证开发者新增环境变量后无需手动跑任何命令即可获得最新类型生产/CI 构建则直接复用已生成好的声明文件避免构建链路出现写文件副作用。3.3 生成产物示例模板仓库中已包含一次生成的成果 src/typing/env/index.d.ts// Automatically generated based on env/index.ts, do not modify manually declare const IS_CI: boolean; declare const IS_DEV_MODE: boolean; declare const IS_PRODUCT_MODE: boolean; declare const IS_SCM: boolean;可以看到声明按变量名排序类型信息此处均为boolean直接取自envs各属性的静态类型。这份文件与 src/typing/global.d.ts声明*.svg、*.png、*.less等模块类型共同构成模板的全局类型层业务代码无需任何 import 即可使用这些全局标识。四、新增一个环境变量的完整操作流程基于上述机制在模板中新增环境变量的标准操作只需两步第一步在 env/index.ts 中读取原始值并加入envsconst IS_FEATURE_X process.env.FEATURE_X true; export const envs { IS_DEV_MODE, IS_PRODUCT_MODE, IS_CI, IS_SCM, IS_FEATURE_X, // 新增项作为 envs 的一组 key-value };第二步本地开发启动自动刷新类型声明执行rushx dev等价于NODE_ENVdevelopment rspack serve见 package.json 的 scripts 定义开发模式下的updateDTS()会自动把IS_FEATURE_X: boolean追加进 src/typing/env/index.d.ts随后即可在任意业务代码中直接使用IS_FEATURE_X并获得完整的类型提示。注意两点约定务必作为envs的成员加入仅定义在文件顶层而未放入envs的变量不会被脚本识别不要手动编辑src/typing/env/index.d.ts改动会在下次开发启动时被覆盖若希望新变量立即可用而暂时不便重启可自行在本地临时执行一次updateDTS脚本。五、多环境地区差异化配置的落地方式README 明确提出可根据多环境地区的环境变量可分别设置相关变量。结合模板的实现差异化的注入点是构建/启动时的进程环境本地开发NODE_ENVdevelopment→IS_DEV_MODE true生产构建NODE_ENVproduction→IS_PRODUCT_MODE trueCI 流水线设置CItrue→IS_CI true同时可按需关闭 tree shaking、输出更详细的 statsSCM/CDN 部署设置BUILD_PATH_SCM及CDN_INNER_CN、CDN_PATH_PREFIX→IS_SCM truepublicPath自动切换为 CDN 地址。不同地区或环境只需在各自的部署配置中注入不同的原始环境变量值业务代码与构建配置均无需修改这正是单一配置入口 归一化语义设计带来的扩展性。六、验证与调试启动开发rushx dev控制台会打印DTS generated in xx ms表示类型声明已刷新同时验证 src/typing/env/index.d.ts 的内容生产构建rushx build等价于NODE_ENVproduction rspack build可观察IS_PRODUCT_MODE分支下的构建行为缺失值排查若后续新增变量在构建期取到undefined构建会直接失败并抛出以下环境变量值为空的异常按提示补全对应环境变量即可。更完整的模板能力React Router、semi 组件库、less/tailwind、vitest 测试、slardar SDK 等可参阅模板根目录的 README.md而环境变量机制本身遵循的正是本模板与 rsbuild-web 等其他子模板共用的配置收敛 类型自动生成工程化范式。七、总结Coze Studio 的 rspack-web 模板通过 env/index.ts配置单一入口、rspack.config.tsDefinePlugin注入 构建行为联动、env/scripts/index.tsts-morph 自动生成类型声明三层结构实现了多环境变量管理的完整闭环新增变量只需改动一处类型提示自动生效构建行为随环境自动切换缺失配置在构建期即被拦截。这套约定对任何基于 Rspack 的前端工程都具有直接的复用价值。【免费下载链接】coze-studioAn AI agent development platform with all-in-one visual tools, simplifying agent creation, debugging, and deployment like never before. Coze your way to AI Agent creation.项目地址: https://gitcode.com/GitHub_Trending/co/coze-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考