以下为本文档的中文说明该技能指导开发者如何在LobeHub等Next.js应用中添加服务端环境变量用于控制用户设置的默认值。其核心功能是建立一套三级优先级体系用户自定义设置 服务端环境变量 硬编码默认值。使用场景包括需要为不同部署环境提供差异化默认配置的场景比如SaaS产品的自托管版本、企业级部署中的自定义白标设置、功能开关的远程控制以及需要在不修改代码的前提下调整应用行为的情况。核心特点在于其清晰的实施流程第一步在src/envs/目录下定义环境变量文件使用Zod模式验证库配合t3-oss/env-nextjs工具包第二步更新TypeScript类型定义在packages/types/src/serverConfig.ts中添加新的配置域第三步创建客户端状态存储使用Zustand等状态管理库定义store schema并设置从环境变量读取的默认值第四步在Provider中消费store通过Hydrate机制在应用启动时从服务端注入默认值。核心原则是’优先级分离’——环境变量仅用于设置默认值用户一旦手动修改环境变量不再覆盖。这种设计既保证了部署的灵活性又尊重用户的选择。该技能还强调了类型安全的重要性所有环境变量都需要经过Zod验证避免运行时出现类型错误。Adding Environment Variable for User SettingsAdd server-side environment variables to configure default values for user settings.Priority: User Custom Server Env Var Hardcoded DefaultSteps1. Define Environment VariableCreatesrc/envs/domain.ts:import{createEnv}fromt3-oss/env-nextjs;import{z}fromzod;exportconstgetDomainConfig(){returncreateEnv({server:{YOUR_ENV_VAR:z.coerce.number().min(MIN).max(MAX).optional(),},runtimeEnv:{YOUR_ENV_VAR:process.env.YOUR_ENV_VAR,},});};exportconstdomainEnvgetDomainConfig();2. Update Type (if new domain)Add topackages/types/src/serverConfig.ts:import{UserDomainConfig}from./user/settings;exportinterfaceGlobalServerConfig{domain?:PartialDeepUserDomainConfig;}Prefer reusing existing typesfrompackages/types/src/user/settings.3. Assemble Server Config (if new domain)Inapps/server/src/globalConfig/index.ts:import{domainEnv}from/envs/domain;exportconstgetServerGlobalConfigasync(){constconfig:GlobalServerConfig{domain:cleanObject({settingName:domainEnv.YOUR_ENV_VAR,}),};returnconfig;};4. Merge to User Store (if new domain)Insrc/store/user/slices/common/action.ts:constserverSettings:PartialDeepUserSettings{domain:serverConfig.domain,};5. Update .env.example# Description (range/options, default: X)# YOUR_ENV_VARexample6. Update Documentationdocs/self-hosting/environment-variables/basic.mdx(EN)docs/self-hosting/environment-variables/basic.zh-CN.mdx(CN)Example: AI_IMAGE_DEFAULT_IMAGE_NUM// src/envs/image.tsAI_IMAGE_DEFAULT_IMAGE_NUM:z.coerce.number().min(1).max(20).optional(),// packages/types/src/serverConfig.tsimage?:PartialDeepUserImageConfig;// apps/server/src/globalConfig/index.tsimage:cleanObject({defaultImageNum:imageEnv.AI_IMAGE_DEFAULT_IMAGE_NUM}),// src/store/user/slices/common/action.tsimage:serverConfig.image,// .env.example#AI_IMAGE_DEFAULT_IMAGE_NUM43c:[“,,,L3f”,null,{“content”:“$40”,“frontMatter”:{“name”:“add-setting-env”,“description”:“Add server-side environment variables that control default values for user settings.”,“disable-model-invocation”:true,“argument-hint”:“[setting-name]”}}]3d:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L41,L41,L41,L42”,“L43,L43,L43,L44”,“L45,L45,L45,L46”]}]]}]]}]47:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]
以下为本文档的中文说明该技能指导开发者如何在LobeHub等Next.js应用中添加服务端环境变量用于控制用户设置的默认值。其核心功能是建立一套三级优先级体系用户自定义设置 服务端环境变量 硬编码默认值。使用场景包括需要为不同部署环境提供差异化默认配置的场景比如SaaS产品的自托管版本、企业级部署中的自定义白标设置、功能开关的远程控制以及需要在不修改代码的前提下调整应用行为的情况。核心特点在于其清晰的实施流程第一步在src/envs/目录下定义环境变量文件使用Zod模式验证库配合t3-oss/env-nextjs工具包第二步更新TypeScript类型定义在packages/types/src/serverConfig.ts中添加新的配置域第三步创建客户端状态存储使用Zustand等状态管理库定义store schema并设置从环境变量读取的默认值第四步在Provider中消费store通过Hydrate机制在应用启动时从服务端注入默认值。核心原则是’优先级分离’——环境变量仅用于设置默认值用户一旦手动修改环境变量不再覆盖。这种设计既保证了部署的灵活性又尊重用户的选择。该技能还强调了类型安全的重要性所有环境变量都需要经过Zod验证避免运行时出现类型错误。Adding Environment Variable for User SettingsAdd server-side environment variables to configure default values for user settings.Priority: User Custom Server Env Var Hardcoded DefaultSteps1. Define Environment VariableCreatesrc/envs/domain.ts:import{createEnv}fromt3-oss/env-nextjs;import{z}fromzod;exportconstgetDomainConfig(){returncreateEnv({server:{YOUR_ENV_VAR:z.coerce.number().min(MIN).max(MAX).optional(),},runtimeEnv:{YOUR_ENV_VAR:process.env.YOUR_ENV_VAR,},});};exportconstdomainEnvgetDomainConfig();2. Update Type (if new domain)Add topackages/types/src/serverConfig.ts:import{UserDomainConfig}from./user/settings;exportinterfaceGlobalServerConfig{domain?:PartialDeepUserDomainConfig;}Prefer reusing existing typesfrompackages/types/src/user/settings.3. Assemble Server Config (if new domain)Inapps/server/src/globalConfig/index.ts:import{domainEnv}from/envs/domain;exportconstgetServerGlobalConfigasync(){constconfig:GlobalServerConfig{domain:cleanObject({settingName:domainEnv.YOUR_ENV_VAR,}),};returnconfig;};4. Merge to User Store (if new domain)Insrc/store/user/slices/common/action.ts:constserverSettings:PartialDeepUserSettings{domain:serverConfig.domain,};5. Update .env.example# Description (range/options, default: X)# YOUR_ENV_VARexample6. Update Documentationdocs/self-hosting/environment-variables/basic.mdx(EN)docs/self-hosting/environment-variables/basic.zh-CN.mdx(CN)Example: AI_IMAGE_DEFAULT_IMAGE_NUM// src/envs/image.tsAI_IMAGE_DEFAULT_IMAGE_NUM:z.coerce.number().min(1).max(20).optional(),// packages/types/src/serverConfig.tsimage?:PartialDeepUserImageConfig;// apps/server/src/globalConfig/index.tsimage:cleanObject({defaultImageNum:imageEnv.AI_IMAGE_DEFAULT_IMAGE_NUM}),// src/store/user/slices/common/action.tsimage:serverConfig.image,// .env.example#AI_IMAGE_DEFAULT_IMAGE_NUM43c:[“,,,L3f”,null,{“content”:“$40”,“frontMatter”:{“name”:“add-setting-env”,“description”:“Add server-side environment variables that control default values for user settings.”,“disable-model-invocation”:true,“argument-hint”:“[setting-name]”}}]3d:[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[[”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected }, got EOF at end of input: …,children:[”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected EOF, got } at position 88: …ldren:同仓库}]]}̲],[”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[,h2,null,{id:related-skills-heading,className:text-2xl font-semibold tracking-normal text-foreground,children:同仓库更多 Skills}],[,h2,null,id:related−skills−heading,className:text−2xlfont−semiboldtracking−normaltext−foreground,children:同仓库更多Skills],[”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L41,L41,L41,L42”,“L43,L43,L43,L44”,“L45,L45,L45,L46”]}]]}]]}]47:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id96nx3k.js,“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,/_next/static/chunks/07k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]
