SuperAPI AI 工具集

sfnext-configuration

前端与建站

查看项目

更新于 10-16 05:42

技能介绍

用途:集中管理 Storefront Next 应用配置。所有配置集中在 config.server.ts,使用带类型的默认值,环境变量(.env 文件或 MRT 设置)可覆盖默认值,并自动解析与校验,提供类型安全访问。

主要能力:新增配置需三步——在 src/types/config.ts 定义类型、在 config.server.ts 设置默认值、通过环境变量覆盖。读取方式分场景:React 组件用 useConfig;服务端 loader/action 用 getConfig(context),context 在服务端必需;浏览器非路由模块用 getConfig()(依赖 window.APP_CONFIG)。两者返回 AppConfig(完整配置的 app 部分),直接访问属性,无需 app 前缀。

环境变量规则:模式为 PUBLIC__app__{path}{to}{property}=value,映射到 config.app 下对应路径;PUBLIC__ 前缀表示暴露给浏览器(客户端安全),无前缀为仅服务端(密钥);__ 分隔嵌套路径;数字、布尔、JSON 自动解析;路径必须存在于 config.server.ts 才会通过校验;嵌套深度上限 10 层;MRT 限制为变量名最长 512 字符,PUBLIC__ 总量最大 32KB。多站点配置通过 PUBLIC__app__commerce__sites 传入 JSON 数组,包含 id、defaultLocale、defaultCurrency、supportedLocales、supportedCurrencies。

安全:客户端安全变量用 PUBLIC__ 前缀;服务端专用密钥不加前缀,永不发送到客户端,应直接读取 process.env,不要加入配置系统。

常见陷阱:服务端 getConfig() 缺少 context 会返回 undefined,应传 context;环境变量拼写错误会被静默忽略,靠路径校验发现;敏感数据勿放入 PUBLIC__ 变量。

相关技能:sfnext-project-setup(环境与 .env 配置)、sfnext-data-fetching(在 loader 中使用配置)、sfnext-deployment(MRT 环境变量配置)。