@ubean/build 0.6.2 → 0.6.4

package/dist/{codegen-DNUCCW3C.js → codegen-BL0s5Pyq.js}

@@ -1,8 +1,89 @@
+import { r as resolveEnvModules } from "./types-JZjwXWJd.js";
 import { isAbsolute, join, normalize, relative } from "pathe";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { glob } from "tinyglobby";
 import { createUnimport, toTypeDeclarationFile } from "unimport";
 import openapiTS, { astToString } from "openapi-typescript";
+//#region src/env/codegen.ts
+/**
+* `.ubean/env.d.ts` 生成器。
+*
+* 两个职责：
+* 1. 给 `ubean:env/client` / `ubean:env/server` 两个虚拟模块补类型（否则用户 import 时 TS2307）
+* 2. 从 Vite 解析好的 `import.meta.env` 自动生成 `ImportMetaEnv`，替掉用户手写的那份
+*
+* 第 2 点顺手修掉一类漂移：手写 `ImportMetaEnv` 会漏 key。本仓库的实例是
+* `src/env.ts` 读了 `import.meta.env.VITE_API_PROXY_KEYS`，而 `src/typings/env.d.ts`
+* 里没有对应声明 —— 手写清单没有东西能提醒它过期。
+*/
+const VITE_BUILTIN_ENV_KEYS = /* @__PURE__ */ new Set([
+	"MODE",
+	"DEV",
+	"PROD",
+	"BASE_URL",
+	"SSR"
+]);
+/**
+* 产物文件名（单一来源：`generateEnvTypes()` 的默认值与 `CODEGEN_NON_CONTRACT_FILES`
+* 都用它，免得改了一处漏另一处）。
+*/
+const ENV_TYPES_FILE_NAME = "env.d.ts";
+function tsTypeOfLiteral(value) {
+	if (typeof value === "number") return "number";
+	if (typeof value === "boolean") return "boolean";
+	return "string";
+}
+function renderModuleTypes(moduleId, fields) {
+	if (fields.length === 0) return `declare module '${moduleId}' {\n  // env.schema is empty\n}\n`;
+	return `declare module '${moduleId}' {\n${fields.map((f) => {
+		return `  export const ${f.key}: ${f.type}${f.optional ? " | undefined" : ""};`;
+	}).join("\n")}\n}\n`;
+}
+/**
+* 从 `import.meta.env` 快照生成 `ImportMetaEnv`。
+*
+* 值同时用于**类型**：字符串字面量能收窄成具体字符串 —— 但只在值是字面量时。这里选择
+* 宽化到 `string` / `number` / `boolean`，因为 `.env` 里的值一律是字符串，写成裸字面量
+* 会让 `VITE_API_ENV` 被推成 `"local"` 这种过窄类型，赋值时报错。
+*/
+function renderImportMetaEnv(importMetaEnv) {
+	const keys = Object.keys(importMetaEnv).filter((key) => key.startsWith("VITE_") || VITE_BUILTIN_ENV_KEYS.has(key)).sort();
+	if (keys.length === 0) return `interface ImportMetaEnv {\n  readonly [key: string]: string | boolean | undefined;\n}\n`;
+	return `interface ImportMetaEnv {\n${keys.map((key) => {
+		const value = importMetaEnv[key];
+		if (VITE_BUILTIN_ENV_KEYS.has(key)) {
+			if (key === "MODE" || key === "BASE_URL") return `  readonly ${key}: string;`;
+			return `  readonly ${key}: boolean;`;
+		}
+		return `  readonly ${key}: ${tsTypeOfLiteral(value)};`;
+	}).join("\n")}\n}\n`;
+}
+/**
+* 生成 `.ubean/env.d.ts`。
+*
+* 顶层**不能**出现 `export {}`：`ImportMetaEnv` 的声明必须留在全局作用域，一旦文件变成
+* 模块，TypeScript 的类型增强就失效（Vite 官方文档专门警告过这一点）。
+* `declare module '...'` 块本身不需要文件是模块。
+*/
+async function generateEnvTypes(options) {
+	const { outDir, fileName = ENV_TYPES_FILE_NAME, modules, importMetaEnv = {} } = options;
+	const contents = `// Auto-generated by ubean from \`env.schema\` in ubean.config.ts — do not edit manually.
+// Provides typed access to \`ubean:env/client\` / \`ubean:env/server\` and declares ImportMetaEnv.
+/* eslint-disable */
+/// <reference types="vite/client" />
+
+${renderImportMetaEnv(importMetaEnv)}
+interface ImportMeta {
+  readonly env: ImportMetaEnv;
+}
+
+${renderModuleTypes("ubean:env/client", modules.client)}${renderModuleTypes("ubean:env/server", modules.server)}`;
+	await mkdir(outDir, { recursive: true });
+	const outPath = join(outDir, fileName);
+	await writeFile(outPath, contents, "utf8");
+	return outPath;
+}
+//#endregion
 //#region src/codegen/auto-imports.ts
 /** 将 `boolean | AutoImportOptions` 归一化为分库开关 + 透传选项。 */
 function resolveAutoImportsConfig(input) {
@@ -851,8 +932,16 @@ const CODEGEN_FILES = [
 		types: []
 	}
 ];
+/**
+* `generateTypes()` 会写、但**不属于**外部冻结契约的产物。
+*
+* 存在的意义只为一个可执行断言服务：`test/codegen-doc-contract.test.ts` 断言「文档里列出的
+* `*.d.ts` 必须在代码里真的产出」，而 `env.d.ts` 故意不进 `CODEGEN_FILES`（理由见那里），
+* 于是它有产物、没契约条目。把名字登记在这里，比在测试里硬编码字符串更难漂移。
+*/
+const CODEGEN_NON_CONTRACT_FILES = [ENV_TYPES_FILE_NAME];
 async function generateTypes(result, options) {
-	const { cwd, srcDir, buildDir, ...autoImportOptions } = options;
+	const { cwd, srcDir, buildDir, env, importMetaEnv, ...autoImportOptions } = options;
 	const outDir = join(cwd, buildDir);
 	await mkdir(outDir, { recursive: true });
 	const generated = [];
@@ -865,6 +954,15 @@ async function generateTypes(result, options) {
 	generated.push(pageTypesPath);
 	const i18nTypesPath = await generateI18nTypes(result, { outDir });
 	if (i18nTypesPath) generated.push(i18nTypesPath);
+	const envTypesPath = await generateEnvTypes({
+		outDir,
+		modules: resolveEnvModules({
+			schema: env?.schema ?? {},
+			importMetaEnv
+		}),
+		importMetaEnv
+	});
+	generated.push(envTypesPath);
 	const { autoImportsDtsPath, componentsDtsPath, virtualComponentsDtsPath } = await generateAutoImports(result, {
 		cwd,
 		srcDir,
@@ -890,8 +988,9 @@ async function generateTypes(result, options) {
 		autoImportsDtsPath,
 		componentsDtsPath,
 		virtualComponentsDtsPath,
+		envTypesPath,
 		generated
 	};
 }
 //#endregion
-export { getUbeanAutoImportConfig as C, toArray as D, resolveComponentsConfig as E, getBuiltinComposables as S, resolveAutoImportsConfig as T, VUE_PRESET as _, generateOpenApiTypesFromServer as a, generateImportsTransform as b, generateI18nTypes as c, COMPONENT_HALF_GLOBS as d, HONO_OPENAPI_PRESET as f, VUE_MACROS_PRESET as g, VUE_I18N_PRESET as h, generateOpenApiTypes as i, messagesToTsType as l, UBEAN_SERVER_PRESET as m, CODEGEN_FILES as n, generatePageTypes as o, UBEAN_CLIENT_PRESET as p, generateTypes as r, generateRouteTypes as s, CODEGEN_CONTRACT_VERSION as t, BUILTIN_PRESETS as u, VUE_ROUTER_PRESET as v, getUbeanComponentsConfig as w, getAutoImportPresets as x, generateAutoImports as y };
+export { getBuiltinComposables as C, resolveComponentsConfig as D, resolveAutoImportsConfig as E, toArray as O, getAutoImportPresets as S, getUbeanComponentsConfig as T, VUE_MACROS_PRESET as _, generateOpenApiTypes as a, generateAutoImports as b, generateRouteTypes as c, BUILTIN_PRESETS as d, COMPONENT_HALF_GLOBS as f, VUE_I18N_PRESET as g, UBEAN_SERVER_PRESET as h, generateTypes as i, generateI18nTypes as l, UBEAN_CLIENT_PRESET as m, CODEGEN_FILES as n, generateOpenApiTypesFromServer as o, HONO_OPENAPI_PRESET as p, CODEGEN_NON_CONTRACT_FILES as r, generatePageTypes as s, CODEGEN_CONTRACT_VERSION as t, messagesToTsType as u, VUE_PRESET as v, getUbeanAutoImportConfig as w, generateImportsTransform as x, VUE_ROUTER_PRESET as y };

package/dist/env/plugin.d.ts

@@ -0,0 +1,89 @@
+import { ResolvedConfig } from "@ubean/config";
+import { Plugin } from "vite";
+//#region src/env/types.d.ts
+/**
+ * `env.schema` → 两个虚拟模块（`ubean:env/client` / `ubean:env/server`）的规范化与取值。
+ *
+ * 这一层刻意与 Vite 无耦合（纯函数 + 显式入参），因为同一个产物要服务两个环境：
+ * - **client 模块**：字段被内联成字面量，取值来自 Vite 已解析好的 `import.meta.env`（构建期）
+ * - **server 模块**：字段从 `process.env` 读（运行期），并在 `mode: 'throw'` 时于 import 期抛错
+ *
+ * 维度规则照抄 Astro `astro:env`：`client+public` / `server+public` / `server+secret` 三种合法，
+ * `client+secret` 在**规范化阶段**就抛错（配置期失败，比构建期失败早）。
+ */
+type EnvContext = 'client' | 'server';
+type EnvAccess = 'public' | 'secret';
+interface EnvFieldSpec {
+  key: string;
+  context: EnvContext;
+  access: EnvAccess;
+  /** TypeScript 字面量类型，直接写进 `.ubean/env.d.ts`。 */
+  type: string;
+  optional: boolean;
+  /**
+   * 已解析的值：
+   * - `context: 'client'` → 构建期内联用的字面量（来自 `import.meta.env` / `.env`，已含 default 回退）
+   * - `context: 'server'` → **`default` 的回退值**（`process.env` 里没值时用）。
+   *   服务端的真实取值发生在运行期，这里只把回退值送到生成代码里。
+   *   字段没写 `default` 时保持 `undefined`，生成代码便能区分「有回退」与「无回退」。
+   */
+  value?: unknown;
+  /** 生成代码里表达「值来自 process.env 的哪个键」——恒等于 `key`（保留字段便于日后加 alias）。 */
+  sourceKey: string;
+}
+interface ResolveEnvModulesInput {
+  /** 归一化 schema（`ResolvedConfig.env.schema`）。 */
+  schema: Record<string, unknown>;
+  /** Vite 解析后的 `import.meta.env`（`ResolvedConfig.env`），用于 client 字段取值。 */
+  importMetaEnv?: Record<string, unknown>;
+  /**
+   * `.env` 文件的原始内容（`loadEnv(mode, envDir, '')`）。
+   *
+   * 与 `importMetaEnv` 的分工：`import.meta.env` 只含 Vite 注入的 key（`VITE_*` + 内建），
+   * 而 `.env` 里有全量。优先 `importMetaEnv`，缺了才回落这里 —— 这样 `MODE` 这类构建期
+   * 派生值不会因为 `.env` 里也写了同名 key 被盖掉。
+   */
+  dotEnv?: Record<string, string>;
+  /** 服务端侧来源，默认 `process.env`。测试可注入。 */
+  serverEnv?: Record<string, string | undefined>;
+}
+interface EnvModules {
+  client: EnvFieldSpec[];
+  server: EnvFieldSpec[];
+}
+/**
+ * 规范化 schema → 两个模块各自的字段清单。
+ *
+ * 值解析失败（缺必填、类型不符、枚举越界）**不在这里报错** —— 那是运行时校验（`resolveEnvSchema()`
+ * 与生成的 server 模块）的职责。这里只负责把维度与类型摊平，缺值时留 `undefined` 让下游决定。
+ */
+export declare function resolveEnvModules(input: ResolveEnvModulesInput): EnvModules;
+/** 生成客户端虚拟模块源码：每个字段一个具名导出的字面量。 */
+export declare function renderEnvClientModule(fields: EnvFieldSpec[]): string;
+/**
+ * 生成服务端虚拟模块源码。
+ *
+ * 语义是 **static**（借 SvelteKit 的术语）：模块求值时读一次 `process.env`，之后固定。
+ * 与 Astro `astro:env/server` 一致 —— 需要 per-request 动态读取时用 `getSecret()`（见下）。
+ *
+ * 校验失败时：`mode: 'throw'` 直接抛，`'warn'`（默认）打 warn 并把缺值放行。
+ * 选择在 import 期抛而不是返回 `undefined`：缺一个必填 secret 却静默跑下去，
+ * 会把「部署忘了配环境变量」拖到第一次请求才炸。
+ */
+export declare function renderEnvServerModule(fields: EnvFieldSpec[], mode?: 'warn' | 'throw'): string;
+//#endregion
+//#region src/env/plugin.d.ts
+export declare const ENV_CLIENT_ID = "ubean:env/client";
+export declare const ENV_SERVER_ID = "ubean:env/server";
+export interface UbeanEnvPluginOptions {
+  /** 已解析配置（`ensureUbeanConfig()` 的产物）。 */
+  config: ResolvedConfig;
+}
+/**
+ * 生成模块所需的信息在 `configResolved` 才能全部拿到：
+ * - `config.env`（Vite 解析后的 `import.meta.env` 快照）由 Vite 在钩子入参里给
+ * - 同一个钩子还会给出 `mode`，用于判定生产/开发（决定 warn 的措辞）
+ */
+export declare function ubeanEnvPlugin(options: UbeanEnvPluginOptions): Plugin;
+//#endregion
+export type { EnvFieldSpec, EnvModules, ResolveEnvModulesInput };

package/dist/env/plugin.js

@@ -0,0 +1,80 @@
+import { n as renderEnvServerModule, r as resolveEnvModules, t as renderEnvClientModule } from "../types-JZjwXWJd.js";
+import { loadEnv } from "vite";
+//#region src/env/plugin.ts
+/**
+* `ubean:env/*` 虚拟模块插件（Astro `astro:env` 的 Vite 版）。
+*
+* 提供两个模块：
+* - `ubean:env/client` — 客户端可见字段，构建期内联成字面量。任何环境都能 import。
+* - `ubean:env/server` — 服务端字段，运行期读 `process.env`。**在客户端环境 import 直接让构建失败**
+*   （这是抄 SvelteKit `$env/static/private` 的护栏；比 Astro 的「类型上没有」更强一层）。
+*
+* 与 `ubean:core` 的关系：本插件**不**进 `VIRTUAL_MODULES` 数组（那是 core 的私有清单），
+* 自己处理 `resolveId`/`load`。好处是两条路径（CLI 自建 builder / 裸 `vite build`）都只需
+* 在 `ubeanPlugin()` 里加一行，core 的 resolveId 顺序不受影响 —— 只要本插件排在 core **之后**
+* 即可（core 只会拦它自己那份清单，不会碰 `ubean:env/*`）。
+*/
+const ENV_CLIENT_ID = "ubean:env/client";
+const ENV_SERVER_ID = "ubean:env/server";
+const RESOLVED_CLIENT = "\0ubean:env/client";
+const RESOLVED_SERVER = "\0ubean:env/server";
+/** 客户端环境名（`createBuildEnvironments()` 里注册的那个）。 */
+const CLIENT_ENVIRONMENT = "client";
+/**
+* 生成模块所需的信息在 `configResolved` 才能全部拿到：
+* - `config.env`（Vite 解析后的 `import.meta.env` 快照）由 Vite 在钩子入参里给
+* - 同一个钩子还会给出 `mode`，用于判定生产/开发（决定 warn 的措辞）
+*/
+function ubeanEnvPlugin(options) {
+	const { config } = options;
+	let importMetaEnv = {};
+	/**
+	* `.env` 文件的原始内容（`loadEnv(mode, envDir, '')`，**不过 prefix 过滤**）。
+	*
+	* 服务端字段的解析来源：`configResolved` 里把它合进 `process.env`，生成的
+	* `ubean:env/server` 模块才能读到 `.env`。不合并的话，`process.env` 里只有真实导出的
+	* 环境变量，`.env` 里写的 `SERVER_PORT` / `JWT_SECRET` 全是 undefined。
+	*/
+	let fileEnv = {};
+	let modules = null;
+	/**
+	* 幂等构建（dev 下 client / ubean 两个环境各跑一次钩子，但结果一致 —— 缓存即可）。
+	*
+	* **不缓存**会被服务端环境污染：`resolveEnvModules()` 的 server 分支会读 `process.env`
+	* 来决定 optional，而两次调用之间 `.env` 不会变，所以缓存是安全的。
+	*/
+	function ensureModules() {
+		if (modules) return modules;
+		modules = resolveEnvModules({
+			schema: config.env?.schema ?? {},
+			dotEnv: fileEnv,
+			importMetaEnv
+		});
+		return modules;
+	}
+	return {
+		name: "ubean:env",
+		enforce: "post",
+		configResolved(resolved) {
+			importMetaEnv = resolved.env;
+			fileEnv = loadEnv(resolved.mode, resolved.envDir ?? resolved.root, "");
+			for (const [key, value] of Object.entries(fileEnv)) if (process.env[key] === void 0) process.env[key] = value;
+			modules = null;
+		},
+		resolveId(id) {
+			if (id === "ubean:env/client") return RESOLVED_CLIENT;
+			if (id === "ubean:env/server") return RESOLVED_SERVER;
+		},
+		load(id) {
+			if (id === RESOLVED_CLIENT) return renderEnvClientModule(ensureModules().client);
+			if (id === RESOLVED_SERVER) {
+				if (this.environment?.name === CLIENT_ENVIRONMENT) throw new Error(`[ubean:env] \`${ENV_SERVER_ID}\` cannot be imported from client code.\nServer env (including \`access: 'secret'\` fields) is never sent to the browser.
+Move the read into server-only code (\`src/routes/**\`, \`src/services/**\`, \`src/db/**\`),
+or declare the field with \`context: 'client', access: 'public'\` if it is safe to inline.`);
+				return renderEnvServerModule(ensureModules().server, config.env?.mode ?? "warn");
+			}
+		}
+	};
+}
+//#endregion
+export { ENV_CLIENT_ID, ENV_SERVER_ID, renderEnvClientModule, renderEnvServerModule, resolveEnvModules, ubeanEnvPlugin };

package/dist/prerender.js

@@ -2,8 +2,8 @@ import { STATIC_NOT_FOUND_ROUTE } from "./static-render.js";
 import { dirname, isAbsolute, join } from "pathe";
 import { resolvePrerenderConfig } from "@ubean/config";
 import { mkdir, writeFile } from "node:fs/promises";
-import { DATA_PAYLOAD_ID } from "@ubean/pages";
 import { matchGlob } from "@ubean/shared";
+import { DATA_PAYLOAD_ID } from "@ubean/pages";
 //#region src/prerender.ts
 const LINK_REGEX = /<a[^>]+href=["']([^"']+)["'][^>]*>/gi;
 /**

package/dist/production.js

@@ -1,2 +1 @@
-import { C as getPresetBuildConfig, S as generateVirtualModulesToDisk, T as buildWithEnvironments, b as generateNodeServerEntry, v as createIslandsSsrStubPlugin, w as serializePagesForEntry, x as generateStandardHandlerEntry, y as generateCloudflareWorkerEntry } from "./vite-CrhHLCqC.js";
-export { buildWithEnvironments, createIslandsSsrStubPlugin, generateCloudflareWorkerEntry, generateNodeServerEntry, generateStandardHandlerEntry, generateVirtualModulesToDisk, getPresetBuildConfig, serializePagesForEntry };
+export { T as buildWithEnvironments, v as createIslandsSsrStubPlugin, y as generateCloudflareWorkerEntry, b as generateNodeServerEntry, x as generateStandardHandlerEntry, S as generateVirtualModulesToDisk, C as getPresetBuildConfig, w as serializePagesForEntry } from "./vite-DR0qiIma.js";

package/dist/types-JZjwXWJd.js

@@ -0,0 +1,160 @@
+import { isEnvFieldMeta } from "@ubean/shared";
+//#region src/env/types.ts
+/**
+* `env.schema` → 两个虚拟模块（`ubean:env/client` / `ubean:env/server`）的规范化与取值。
+*
+* 这一层刻意与 Vite 无耦合（纯函数 + 显式入参），因为同一个产物要服务两个环境：
+* - **client 模块**：字段被内联成字面量，取值来自 Vite 已解析好的 `import.meta.env`（构建期）
+* - **server 模块**：字段从 `process.env` 读（运行期），并在 `mode: 'throw'` 时于 import 期抛错
+*
+* 维度规则照抄 Astro `astro:env`：`client+public` / `server+public` / `server+secret` 三种合法，
+* `client+secret` 在**规范化阶段**就抛错（配置期失败，比构建期失败早）。
+*/
+function typeOfField(def) {
+	if (isEnvFieldMeta(def)) {
+		if (def.type === "enum") return (def.values ?? []).map((v) => JSON.stringify(v)).join(" | ") || "string";
+		if (def.type === "number") return "number";
+		if (def.type === "boolean") return "boolean";
+		return "string";
+	}
+	const legacy = def;
+	if (legacy.type === Number) return "number";
+	if (legacy.type === Boolean) return "boolean";
+	if (legacy.type === String) return "string";
+	return "unknown";
+}
+function dimensionsOf(def) {
+	if (isEnvFieldMeta(def)) return {
+		context: def.context,
+		access: def.access
+	};
+	return {
+		context: "server",
+		access: "secret"
+	};
+}
+/**
+* 规范化 schema → 两个模块各自的字段清单。
+*
+* 值解析失败（缺必填、类型不符、枚举越界）**不在这里报错** —— 那是运行时校验（`resolveEnvSchema()`
+* 与生成的 server 模块）的职责。这里只负责把维度与类型摊平，缺值时留 `undefined` 让下游决定。
+*/
+function resolveEnvModules(input) {
+	const { schema, importMetaEnv = {}, dotEnv = {}, serverEnv = process.env } = input;
+	const client = [];
+	const server = [];
+	for (const [key, def] of Object.entries(schema)) {
+		const { context, access } = dimensionsOf(def);
+		if (context === "client" && access === "secret") throw new Error(`Invalid env field "${key}": context 'client' cannot be combined with access 'secret'. Secrets never reach the client — use \`{ context: 'server', access: 'secret' }\`.`);
+		const meta = isEnvFieldMeta(def) ? def : null;
+		const optional = meta ? meta.optional === true : false;
+		const spec = {
+			key,
+			context,
+			access,
+			type: typeOfField(def),
+			optional,
+			sourceKey: key
+		};
+		if (context === "client") {
+			const raw = importMetaEnv[key] ?? dotEnv[key];
+			const resolved = raw === void 0 || raw === "" ? meta?.default : raw;
+			if (resolved !== void 0) spec.value = resolved;
+			client.push(spec);
+		} else {
+			const hasDefault = meta ? meta.default !== void 0 : def.default !== void 0;
+			const rawServer = serverEnv[key];
+			spec.optional = optional || !hasDefault && (rawServer === void 0 || rawServer === "");
+			if (hasDefault) spec.value = meta ? meta.default : def.default;
+			server.push(spec);
+		}
+	}
+	return {
+		client,
+		server
+	};
+}
+/** 生成客户端虚拟模块源码：每个字段一个具名导出的字面量。 */
+function renderEnvClientModule(fields) {
+	const lines = ["// Generated by ubean from `env.schema` in ubean.config.ts — do not edit.", "// Values are inlined at build time from Vite-resolved `import.meta.env`."];
+	for (const field of fields) {
+		if (field.value === void 0) {
+			lines.push(`// ${field.key}: no value resolved at build time${field.optional ? " (optional)" : ""}`);
+			lines.push(`export const ${field.key} = undefined;`);
+			continue;
+		}
+		lines.push(`export const ${field.key} = ${JSON.stringify(field.value)};`);
+	}
+	return `${lines.join("\n")}\n`;
+}
+/**
+* 生成服务端虚拟模块源码。
+*
+* 语义是 **static**（借 SvelteKit 的术语）：模块求值时读一次 `process.env`，之后固定。
+* 与 Astro `astro:env/server` 一致 —— 需要 per-request 动态读取时用 `getSecret()`（见下）。
+*
+* 校验失败时：`mode: 'throw'` 直接抛，`'warn'`（默认）打 warn 并把缺值放行。
+* 选择在 import 期抛而不是返回 `undefined`：缺一个必填 secret 却静默跑下去，
+* 会把「部署忘了配环境变量」拖到第一次请求才炸。
+*/
+function renderEnvServerModule(fields, mode = "warn") {
+	const specs = fields.map((f) => ({
+		key: f.key,
+		type: f.type === "number" ? "number" : f.type === "boolean" ? "boolean" : "string",
+		optional: f.optional,
+		default: f.value
+	}));
+	return `// Generated by ubean from \`env.schema\` in ubean.config.ts — do not edit.
+// Reads \`process.env\` once, at module evaluation time (static semantics).
+
+const __specs = ${JSON.stringify(specs)};
+const __source = typeof process !== 'undefined' && process.env ? process.env : {};
+const __errors = [];
+const __values = {};
+
+for (const spec of __specs) {
+  const raw = __source[spec.key];
+  if (raw === undefined || raw === '') {
+    if (spec.default !== undefined) {
+      __values[spec.key] = spec.default;
+      continue;
+    }
+    if (!spec.optional) __errors.push(\`  - \${spec.key}: Missing required env\`);
+    __values[spec.key] = undefined;
+    continue;
+  }
+  if (spec.type === 'number') {
+    const n = Number(raw);
+    if (Number.isNaN(n)) {
+      __errors.push(\`  - \${spec.key}: must be a number, got \${raw}\`);
+      __values[spec.key] = undefined;
+      continue;
+    }
+    __values[spec.key] = n;
+    continue;
+  }
+  if (spec.type === 'boolean') {
+    __values[spec.key] = raw === 'true' || raw === '1';
+    continue;
+  }
+  __values[spec.key] = raw;
+}
+
+if (__errors.length > 0) {
+  const message = 'Environment validation failed:\\n' + __errors.join('\\n');
+  if (${JSON.stringify(mode)} === 'throw') throw new Error(message);
+  // eslint-disable-next-line no-console
+  console.warn('[ubean:env/server] ' + message);
+}
+
+export const __env = __values;
+${fields.map((f) => `export const ${f.key} = __values[${JSON.stringify(f.key)}];`).join("\n")}
+
+/** 读取未在 \`env.schema\` 里声明的变量（动态 / per-request 场景）。 */
+export function getSecret(key) {
+  return __source[key];
+}
+`;
+}
+//#endregion
+export { renderEnvServerModule as n, resolveEnvModules as r, renderEnvClientModule as t };

package/dist/{vite-CrhHLCqC.js → vite-DR0qiIma.js}

@@ -1,13 +1,13 @@
 import { a as ssrSingletonProdOptimizeExclude, m as createVirtualRegistry, o as ssrSingletonProdSsr, y as __exportAll } from "./ssr-singleton-Bbds29jS.js";
 import { a as createRoutingVirtualModule, i as createPagesVirtualModule, n as createLocalesVirtualModule, r as createMetaVirtualModule, s as transformMacros, t as createAppVirtualModule } from "./virtual-modules-BK0L1Op-.js";
-import { i as generateOpenApiTypes, r as generateTypes } from "./codegen-DNUCCW3C.js";
-import { _ as toWebRequest, a as createVueAppEntryVirtualModule, b as getDevScanCoordinator, g as sendWebResponse, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, u as ensureDevApp } from "./vue-DTMMMa4v.js";
+import { a as generateOpenApiTypes, i as generateTypes } from "./codegen-BL0s5Pyq.js";
+import { _ as toWebRequest, a as createVueAppEntryVirtualModule, b as getDevScanCoordinator, g as sendWebResponse, i as createServerEntryVirtualModule, n as ubeanVite, o as createVuePagesVirtualModule, r as createClientEntryVirtualModule, u as ensureDevApp } from "./vue-MyIMqUw0.js";
 import { createStaticSsgRenderer } from "./static-render.js";
 import { prerender, resolvePrerenderStaticDir } from "./prerender.js";
 import { dirname, join, relative, resolve } from "pathe";
 import * as nodeFs from "node:fs";
 import { existsSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
-import { loadUbeanConfig, resolveModules, resolvePrerenderConfig, tryGetConfig } from "@ubean/config";
+import { checkProjectDependenciesOnce, loadUbeanConfig, resolveModules, resolvePrerenderConfig, tryGetConfig } from "@ubean/config";
 import { isEphemeralCachePreset, registerBuiltinPresets, resolvePresetByName, resolveProductionCacheStore } from "@ubean/preset";
 import { createServerRouter } from "@ubean/routes";
 import { scanProject } from "@ubean/scan";
@@ -356,8 +356,14 @@ const RESOLVED_ID = `\0${ASSET_MANIFEST_VIRTUAL_ID}`;
 /**
 * 从 client manifest 算出资产标签。
 *
-* 与旧运行时逻辑逐字等价（`<script type="module" src="/…">` + 每个 css 一个 `<link>`），
-* 只是执行时机从「服务端启动时」提前到「服务端构建时」。
+* CSS 取**全量 chunk 的并集**，而不是只读 entry：代码分割后页面/布局的样式落在各自的 chunk 上，
+* entry 的 `css` 常常是空的（实测 `examples/ubean-test` 为 0 条），只读 entry 会让生产 HTML
+* 首帧无样式（FOUC）—— 与 dev 侧 `collectDevCssLinks` 读 client 图为空是同一类缺陷。
+* entry 自己的 css 排在前面，其余按文件名排序，保证构建可重现。
+*
+* 代价：会多加载未访问页面的 CSS（实测 ubean-test 15 个 chunk 共 12.0KB、docs 仅 +0.3KB）。
+* 若要收敛到「只注入当前页实际用到的」，需要走 ssr-manifest + 渲染期收集（见 dev 侧的
+* `isCssModuleUrl` 路径），属于更大的改造。
 */
 function computeAssetTags(manifest, favicon) {
 	const tags = {
@@ -366,10 +372,16 @@ function computeAssetTags(manifest, favicon) {
 		body: "",
 		favicon: favicon ?? null
 	};
-	const entry = manifest ? Object.values(manifest).find((item) => item.isEntry) : void 0;
+	const entries = manifest ? Object.values(manifest) : [];
+	const entry = entries.find((item) => item.isEntry);
 	if (!entry) return tags;
 	tags.body = `<script type="module" src="/${entry.file}"><\/script>`;
-	if (Array.isArray(entry.css)) tags.css = entry.css.map((css) => `<link rel="stylesheet" href="/${css}">`).join("\n");
+	const cssFiles = /* @__PURE__ */ new Set();
+	for (const css of entry.css ?? []) cssFiles.add(css);
+	const rest = /* @__PURE__ */ new Set();
+	for (const item of entries) for (const css of item.css ?? []) if (!cssFiles.has(css)) rest.add(css);
+	for (const css of [...rest].sort()) cssFiles.add(css);
+	if (cssFiles.size > 0) tags.css = [...cssFiles].map((css) => `<link rel="stylesheet" href="/${css}">`).join("\n");
 	return tags;
 }
 /** 从磁盘读 client manifest（`<publicDir>/.vite/manifest.json`）。 */
@@ -2490,6 +2502,14 @@ function ubeanPlugin(options) {
 	/** 已跑过 codegen 的扫描结果（`buildStart` 会在两个环境各跑一次）。 */
 	let lastCodegenScan = null;
 	/**
+	* 本插件实例拿到的 Vite 解析后环境变量快照（`configResolved` 钩子填充）。
+	*
+	* 为什么不在 `runProjectCodegen` 里自己 `loadEnv()`：Vite 已经在 `configResolved` 把
+	* **合并完 `.env` / `.env.local` / `.env.[mode]` / 进程环境**的结果给了插件，再自己读一遍
+	* 就多一份可能漂移的实现（优先级规则容易抄错），而且与 `import.meta.env` 的实际内容未必一致。
+	*/
+	let resolvedImportMetaEnv = {};
+	/**
 	* dev 扫描协调器（`configureServer` 建立、`buildStart` 用）。
 	*
 	* Vite 的顺序是 `configureServer` → `buildStart`，且 dev 下每个环境各跑一次 `buildStart`
@@ -2538,6 +2558,16 @@ function ubeanPlugin(options) {
 				ubeanConfig = await loadUbeanConfig();
 				ensureDerived();
 			}
+			if (!process.env.UBEAN_SKIP_DEP_CHECK) await checkProjectDependenciesOnce({
+				cwd: ubeanConfig.rootDir,
+				config: ubeanConfig,
+				srcDir: ubeanConfig.srcDir,
+				mode: "prompt",
+				logger: {
+					info: (message) => logger.info(message),
+					warn: (message) => logger.warn(message)
+				}
+			});
 			if (process.env.UBEAN_BUILD_DRIVEN_BY_CLI === "1") return void 0;
 			return {
 				/**
@@ -2574,6 +2604,9 @@ function ubeanPlugin(options) {
 				environments: await buildEnvironmentsForConfig(ubeanConfig)
 			};
 		},
+		configResolved(resolved) {
+			resolvedImportMetaEnv = resolved.env;
+		},
 		async buildStart() {
 			if (!ubeanConfig) {
 				ubeanConfig = await loadUbeanConfig();
@@ -2756,7 +2789,9 @@ function ubeanPlugin(options) {
 				buildDir: ".ubean",
 				dirs: ubeanConfig.dir,
 				autoImports: ubeanConfig.autoImports,
-				components: ubeanConfig.components
+				components: ubeanConfig.components,
+				env: ubeanConfig.env,
+				importMetaEnv: resolvedImportMetaEnv
 			});
 		} catch (err) {
 			logger.warn(`Failed to generate type definitions: ${err instanceof Error ? err.message : String(err)}`);

package/dist/vite.d.ts

@@ -135,16 +135,21 @@ export declare function isFrameworkHtmlPage(url: string): boolean;
  */
 export declare function isViteResourceRequest(url: string, headers?: IncomingMessage['headers']): boolean;
 /**
- * 从客户端模块图收集 render-blocking CSS 链接。
+ * 收集 render-blocking CSS 链接。
  *
- * dev 下由 JS 引入的 CSS（虚拟 uno.css 入口、全局样式、字体 css）要等客户端模块图执行完才生效，
- * SSR HTML 在这段间隙是**无样式**的（FOUC）。把同一批 CSS 以阻塞 `<link>` 注入，浏览器可与 JS
- * 并行抓取，首屏即有样式。
+ * dev 下由 JS 引入的 CSS 要等模块图执行完才生效，SSR HTML 在这段间隙是**无样式**的（FOUC）。
+ * 把同一批 CSS 以阻塞 `<link>` 注入，浏览器可与 JS 并行抓取，首屏即有样式。
+ *
+ * 数据源是 **ssr + client 两个模块图**，缺一不可：
+ * - `client` 提供客户端入口 import 的全局样式（虚拟 uno.css、`@vean/ui/styles.css`）；
+ * - `ssr` 提供 SFC `<style>` 块，且**首次页面请求时 client 图是空的**（它由浏览器后续请求
+ *   客户端入口才填充）—— 只读 client 图等于首个请求永远注入 0 个链接，正是 FOUC 的来源。
  *
  * `?direct` 让 Vite 的 transform 中间件返回原始 CSS（`Content-Type: text/css`）而不是注入式 JS
- * 包装；URL 自带查询串的模块（SFC `<style>` 块形如 `*.vue?vue&type=style`）无法这样服务，跳过。
+ * 包装。它必须紧跟路径（`?direct&vue&…`）：Vite 的 `CSS_LANGS_RE` 只认 `.css` 结尾或紧跟
+ * `?`，写成 `&lang.css&direct` 会落到 JS 分支，浏览器拒绝把 JS 当样式表。
  */
-export declare function collectDevCssLinks(moduleGraph: ViteDevServer['environments']['client']['moduleGraph']): string[];
+export declare function collectDevCssLinks(server: ViteDevServer): string[];
 /** 在 `</head>` 前插入阻塞样式链接。 */
 export declare function injectStylesheetLinks(html: string, hrefs: string[]): string;
 interface DevRequestRouterOptions {

package/dist/vite.js

@@ -1,4 +1,4 @@
 import { m as createVirtualRegistry } from "./ssr-singleton-Bbds29jS.js";
-import { A as toVueRouterPagePath, C as bootstrapDevApp, D as resolveLocaleVueParam, E as resolveDevSecurityHeaders, O as enhanceDevApp, S as peekDevScanCoordinator, T as createDevAppReady, _ as toWebRequest, b as getDevScanCoordinator, c as collectDevCssLinks, d as getDevApp, f as injectStylesheetLinks, g as sendWebResponse, h as ubeanDevRequestPlugin, k as buildDevSsrRoutes, l as createUbeanRequestHandlers, m as isViteResourceRequest, p as isFrameworkHtmlPage, s as DEVTOOLS_PASS_THROUGH_PREFIXES, u as ensureDevApp, v as DEV_SCAN_DIRS, w as createDevApp, x as onDevScan, y as createDevScanCoordinator } from "./vue-DTMMMa4v.js";
-import { D as createCloudflarePreviewRunner, E as MINIFLARE_INSTALL_HINT, O as defaultLoadMiniflare, _ as ubeanPreviewPlugin, a as createEnvRunnerTransport, c as getDevWorkerEntrySource, d as attachPreviewMiddleware, f as createPreviewMiddleware, g as sendPreviewStatus, h as sendPreviewFile, i as bridgeEnvRunnerInvokes, k as readCompatibilityDate, l as invalidateDevWorkerModules, m as resolvePreviewFile, n as UBEAN_DEV_ENV_NAME, o as createUbeanDevEnvironmentFactory, p as previewMimeType, r as UbeanDevEnvironment, s as DEV_WORKER_FILE, t as ubeanPlugin, u as writeDevWorkerEntry } from "./vite-CrhHLCqC.js";
+import { A as toVueRouterPagePath, C as bootstrapDevApp, D as resolveLocaleVueParam, E as resolveDevSecurityHeaders, O as enhanceDevApp, S as peekDevScanCoordinator, T as createDevAppReady, _ as toWebRequest, b as getDevScanCoordinator, c as collectDevCssLinks, d as getDevApp, f as injectStylesheetLinks, g as sendWebResponse, h as ubeanDevRequestPlugin, k as buildDevSsrRoutes, l as createUbeanRequestHandlers, m as isViteResourceRequest, p as isFrameworkHtmlPage, s as DEVTOOLS_PASS_THROUGH_PREFIXES, u as ensureDevApp, v as DEV_SCAN_DIRS, w as createDevApp, x as onDevScan, y as createDevScanCoordinator } from "./vue-MyIMqUw0.js";
+import { D as createCloudflarePreviewRunner, E as MINIFLARE_INSTALL_HINT, O as defaultLoadMiniflare, _ as ubeanPreviewPlugin, a as createEnvRunnerTransport, c as getDevWorkerEntrySource, d as attachPreviewMiddleware, f as createPreviewMiddleware, g as sendPreviewStatus, h as sendPreviewFile, i as bridgeEnvRunnerInvokes, k as readCompatibilityDate, l as invalidateDevWorkerModules, m as resolvePreviewFile, n as UBEAN_DEV_ENV_NAME, o as createUbeanDevEnvironmentFactory, p as previewMimeType, r as UbeanDevEnvironment, s as DEV_WORKER_FILE, t as ubeanPlugin, u as writeDevWorkerEntry } from "./vite-DR0qiIma.js";
 export { DEVTOOLS_PASS_THROUGH_PREFIXES, DEV_SCAN_DIRS, DEV_WORKER_FILE, MINIFLARE_INSTALL_HINT, UBEAN_DEV_ENV_NAME, UbeanDevEnvironment, attachPreviewMiddleware, bootstrapDevApp, bridgeEnvRunnerInvokes, buildDevSsrRoutes, collectDevCssLinks, createCloudflarePreviewRunner, createDevApp, createDevAppReady, createDevScanCoordinator, createEnvRunnerTransport, createPreviewMiddleware, createUbeanDevEnvironmentFactory, createUbeanRequestHandlers, createVirtualRegistry, defaultLoadMiniflare, enhanceDevApp, ensureDevApp, getDevApp, getDevScanCoordinator, getDevWorkerEntrySource, injectStylesheetLinks, invalidateDevWorkerModules, isFrameworkHtmlPage, isViteResourceRequest, onDevScan, peekDevScanCoordinator, previewMimeType, readCompatibilityDate, resolveDevSecurityHeaders, resolveLocaleVueParam, resolvePreviewFile, sendPreviewFile, sendPreviewStatus, sendWebResponse, toVueRouterPagePath, toWebRequest, ubeanDevRequestPlugin, ubeanPlugin, ubeanPreviewPlugin, writeDevWorkerEntry };