企业官网建设流程全解析

以下为本文档的中文说明

该技能指导开发者如何在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 Settings

Add server-side environment variables to configure default values for user settings.

Priority: User Custom > Server Env Var > Hardcoded Default

Steps

1. Define Environment Variable

Createsrc/envs/<domain>.ts:

import{createEnv}from'@t3-oss/env-nextjs';import{z}from'zod';exportconstget<Domain>Config=()=>{returncreateEnv({server:{YOUR_ENV_VAR:z.coerce.number().min(MIN).max(MAX).optional(),},runtimeEnv:{YOUR_ENV_VAR:process.env.YOUR_ENV_VAR,},});};exportconst<domain>Env=get<Domain>Config();

2. Update Type (if new domain)

Add topackages/types/src/serverConfig.ts:

import{User<Domain>Config}from'./user/settings';exportinterfaceGlobalServerConfig{<domain>?:PartialDeep<User<Domain>Config>;}

Prefer reusing existing typesfrompackages/types/src/user/settings.

3. Assemble Server Config (if new domain)

Inapps/server/src/globalConfig/index.ts:

import{<domain>Env}from'@/envs/<domain>';exportconstgetServerGlobalConfig=async()=>{constconfig:GlobalServerConfig={<domain>:cleanObject({<settingName>:<domain>Env.YOUR_ENV_VAR,}),};returnconfig;};

4. Merge to User Store (if new domain)

Insrc/store/user/slices/common/action.ts:

constserverSettings:PartialDeep<UserSettings>={<domain>:serverConfig.<domain>,};

5. Update .env.example

# <Description> (range/options, default: X)# YOUR_ENV_VAR=<example>

6. Update Documentation

• docs/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?:PartialDeep<UserImageConfig>;// 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_NUM=4

3c:[“","","","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/0bn6id9_{6nx3k.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/0}7k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]