@finesoft/front 0.1.15 → 0.1.17

package/README.md

@@ -1,219 +1,842 @@
 # @finesoft/front
 
-Full-stack framework for building content-driven web applications with SSR support.
+`@finesoft/front` 是一个**聚合型全栈框架包**：
 
-## Features
+- 用 `@finesoft/core` 负责 **路由 / Intent / Controller / DI / Framework**
+- 用 `@finesoft/browser` 负责 **客户端启动、导航、hydrate**
+- 用 `@finesoft/ssr` 负责 **SSR 渲染与数据注入**
+- 用 `@finesoft/server` 负责 **Hono + Vite + 部署适配器**
 
--   **Router** — file-system-style route definitions with intent-driven navigation
--   **DI Container** — lightweight dependency injection for controllers and services
--   **Actions & Intents** — declarative navigation model (FlowAction, ExternalUrlAction)
--   **SSR** — server-side rendering pipeline with data serialization
--   **Server** — one-shot factory for Hono + Vite + SSR (Node / Deno / Bun)
--   **Browser Runtime** — app bootstrap, action handlers, history management
--   **Browser Export Condition** — browser builds exclude server-only code automatically
+如果你想做一个“**URL → Intent → Controller → Page Model → SSR + Hydration**”的内容型站点，这个包就是把整条链路打包好了。
 
-## Install
+这份 README 不讲空话，直接按“**你现在要怎么接入**”来写。照着做，基本就能跑起来。
 
-### Browser-only usage
+---
+
+## 先搞清楚：这个包适合什么项目
+
+它更适合下面这类应用：
+
+- 内容展示站点
+- App Store / Media / 资讯 / 榜单 / 搜索 / 详情页
+- 需要 SSR 的站点
+- URL 和页面状态关系清晰的项目
+- 希望把“页面逻辑”收敛到 Controller，而不是散落在 UI 组件里的项目
+
+如果你的项目是：
+
+- 纯客户端小工具
+- 页面非常少
+- 不需要 SSR / SEO
+
+也能用，但可能有点“杀鸡用框架刀”。
+
+---
+
+## 这个包实际导出了什么
+
+`@finesoft/front` 不是单一模块，而是下面几个能力的统一入口。
+
+### Core
+
+- `Framework`
+- `Router`
+- `Container`
+- `BaseController`
+- `defineRoutes`
+- `ActionDispatcher`
+- `IntentDispatcher`
+- `HttpClient`
+- `LruMap`
+- `buildUrl`
+
+### Browser
+
+- `startBrowserApp`
+- `History`
+- `registerActionHandlers`
+- `registerFlowActionHandler`
+- `registerExternalUrlHandler`
+- `deserializeServerData`
+- `createPrefetchedIntentsFromDom`
+- `tryScroll`
+
+### SSR
+
+- `createSSRRender`
+- `ssrRender`
+- `injectSSRContent`
+- `serializeServerData`
+- `SSR_PLACEHOLDERS`
+
+### Server / Deployment
+
+- `createServer`
+- `createSSRApp`
+- `startServer`
+- `parseAcceptLanguage`
+- `detectRuntime`
+- `resolveRoot`
+- `finesoftFrontViteConfig`
+- `nodeAdapter`
+- `vercelAdapter`
+- `cloudflareAdapter`
+- `netlifyAdapter`
+- `staticAdapter`
+- `autoAdapter`
+- `resolveAdapter`
+
+---
+
+## 三种接入方式，怎么选
+
+### 方案 A：**推荐**，直接用 Vite 插件一把梭
+
+适合绝大多数项目。
+
+你会得到：
+
+- `vite`：开发
+- `vite build`：客户端 + SSR + adapter 一起构建
+- `vite preview`：本地预览 SSR 产物
+
+入口是：`finesoftFrontViteConfig()`
+
+> 如果你没有特殊原因，优先选这个。它是现在这套代码里最顺手的工作流。
+
+### 方案 B：手动用 `createServer()`
+
+适合：
+
+- 你不想依赖 Vite 插件生命周期
+- 你已经有自己的服务启动逻辑
+- 你要手工控制 Hono/Vite/SSR 的集成方式
+
+### 方案 C：纯浏览器使用
+
+适合：
+
+- 不做 SSR
+- 只想复用 Router / Framework / Action / Controller 这套模型
+
+---
+
+## 安装
+
+### 只做浏览器端
 
 ```bash
-npm install @finesoft/front
+pnpm add @finesoft/front
 ```
 
-### SSR / full-stack usage
+### 做 SSR / Vite / 部署适配
+
+```bash
+pnpm add @finesoft/front hono @hono/node-server vite
+```
 
-If you use `createServer()` or other server exports, install the peer dependencies too:
+### 如果你希望 `createServer()` 自动加载 `.env`
 
 ```bash
-npm install @finesoft/front hono vite @hono/node-server dotenv
+pnpm add dotenv
 ```
 
-### Peer dependencies
+### 关于 peerDependencies
 
--   `hono` — required for server usage
--   `vite` — required for development SSR server usage
--   `@hono/node-server` — required for Node.js server startup
--   `dotenv` — optional, only needed if you want `.env` auto-loading in `createServer()`
+这个包当前依赖这些 peer：
 
-## Package entry behavior
+- `hono`
+- `@hono/node-server`
+- `vite`
 
-`@finesoft/front` ships a browser-aware export map.
+也就是说：**浏览器-only 项目**不一定都要装全；但只要你用了 SSR / server / Vite 插件，就请把它们装上。
 
--   In browser bundles, the `browser` condition resolves to the browser-only entry and excludes server code.
--   In SSR / Node environments, the default import resolves to the full entry with browser + SSR + server exports.
+---
 
-That means you can keep importing from:
+## 浏览器与服务端入口行为
+
+`@finesoft/front` 带有 `browser` export condition。
+
+这意味着：
+
+- 浏览器构建时，导入 `@finesoft/front` 会自动走 **browser-only entry**
+- Node / SSR 环境下，导入 `@finesoft/front` 会走 **完整入口**
+
+所以大多数情况下你可以放心写：
 
 ```ts
 import { startBrowserApp } from "@finesoft/front";
 ```
 
-and modern bundlers will avoid pulling in `createServer`, `startServer`, and other server-only code on the client side.
+现代 bundler 会尽量避免把服务端代码拖进浏览器包里。
 
-## Quick Start
+---
 
-### Server
+## 最推荐的用法：Vite + SSR + Hydration + Adapter
 
-```ts
-import { createServer } from "@finesoft/front";
+下面是一个最小可工作的接入方式。
 
-const { app } = await createServer({
-	locales: ["en-US", "zh-CN"],
-	defaultLocale: "en-US",
-	port: 3000,
-	ssr: { ssrEntryPath: "/src/ssr.ts" },
-	setup(app) {
-		// register custom routes on the Hono app
-	},
-});
+### 第 1 步：准备文件结构
+
+建议至少有这些文件：
+
+```text
+src/
+  browser.ts
+  ssr.ts
+  lib/
+    bootstrap.ts
+    controllers/
+      home-controller.ts
+index.html
+vite.config.ts
 ```
 
-Notes:
+如果你还要注册 API 代理或自定义 Hono 路由，再加一个：
 
--   `root` defaults to `process.cwd()`
--   `port` defaults to `process.env.PORT ?? 3000`
--   if a `.env` file exists at the project root, `createServer()` will try to load it automatically
+```text
+src/proxies.ts
+```
 
-### Browser
+---
+
+### 第 2 步：写 `index.html`
+
+你的 HTML 模板**必须包含**这四个 SSR 占位符：
+
+```html
+<!doctype html>
+<html lang="<!--ssr-lang-->">
+	<head>
+		<meta charset="utf-8" />
+		<meta name="viewport" content="width=device-width, initial-scale=1" />
+		<!--ssr-head-->
+	</head>
+	<body>
+		<div id="app"><!--ssr-body--></div>
+		<!--ssr-data-->
+		<script type="module" src="/src/browser.ts"></script>
+	</body>
+</html>
+```
+
+它们的含义如下：
+
+| 占位符 | 会被替换成什么 |
+| --- | --- |
+| `<!--ssr-lang-->` | 当前语言，如 `en` / `zh` |
+| `<!--ssr-head-->` | `<head>` 内容和样式 |
+| `<!--ssr-body-->` | 服务端渲染后的 HTML |
+| `<!--ssr-data-->` | 序列化后的 server data 脚本 |
+
+如果少一个，SSR 体验就会开始闹脾气。
+
+---
+
+### 第 3 步：写路由和 Controller 注册
+
+推荐用 `defineRoutes()`，把 URL 和 Controller 写在同一个数组里。
+
+`src/lib/bootstrap.ts`：
 
 ```ts
-import { startBrowserApp, Framework, defineRoutes } from "@finesoft/front";
+import {
+	BaseController,
+	Container,
+	Framework,
+	defineRoutes,
+	type RouteDefinition,
+} from "@finesoft/front";
+
+class HomeController extends BaseController<Record<string, string>, { title: string }> {
+	readonly intentId = "home-page";
+
+	async execute(_params: Record<string, string>, _container: Container) {
+		return { title: "Home" };
+	}
+}
 
-function bootstrap(framework: Framework) {
-	defineRoutes(framework, [
-		{ path: "/", intentId: "home-page", controller: new HomeController() },
-		{
-			path: "/app/:id",
-			intentId: "product-page",
-			controller: new ProductController(),
-		},
-	]);
+const routes: RouteDefinition[] = [
+	{ path: "/", intentId: "home-page", controller: new HomeController() },
+];
+
+export function bootstrap(framework: Framework): void {
+	defineRoutes(framework, routes);
 }
 
+// 如果你会使用 static adapter，请务必把 routes 导出出来
+export { routes };
+```
+
+#### 为什么 `static` 模式一定要导出 `routes`
+
+因为 `staticAdapter()` 会在构建时去读取你的路由定义，自动预渲染无参数页面。
+
+如果不导出，静态构建就没法知道应该预渲染哪些 URL。
+
+---
+
+### 第 4 步：写浏览器入口 `src/browser.ts`
+
+```ts
+import { startBrowserApp } from "@finesoft/front";
+import { bootstrap } from "$lib/bootstrap";
+
 startBrowserApp({
 	bootstrap,
+	defaultLocale: "en",
 	mountId: "app",
 	mount: (target, { framework, locale }) => {
-		// mount your app (Svelte / React / Vue)
-		return ({ page }) => {
-			/* update on navigation */
+		// 这里接入你的 UI 框架（Svelte / React / Vue 都行）
+		// 返回一个 update 函数，后续导航时会调用它
+		return ({ page, isFirstPage }) => {
+			void target;
+			void framework;
+			void locale;
+			void page;
+			void isFirstPage;
 		};
 	},
 	callbacks: {
-		onNavigationStart: () => {},
-		onNavigationEnd: () => {},
+		onNavigate(pathname) {
+			console.log("navigated:", pathname);
+		},
+		onModal(page) {
+			console.log("open modal:", page);
+		},
 	},
 });
 ```
 
-Notes:
+这里有两个很重要的回调：
+
+- `onNavigate(pathname)`：正常页面跳转后调用
+- `onModal(page)`：当 `FlowAction` 以 modal 方式展示时调用
 
--   `mountId` defaults to `"app"`
--   `locale` is resolved from `document.documentElement.lang` first, then falls back to `defaultLocale`
--   `startBrowserApp()` automatically reads prefetched server data from the DOM and performs the initial route action
+---
 
-### SSR Entry
+### 第 5 步：写 SSR 入口 `src/ssr.ts`
 
 ```ts
 import { createSSRRender, serializeServerData } from "@finesoft/front";
+import { bootstrap } from "$lib/bootstrap";
 
 export const render = createSSRRender({
 	bootstrap,
-	getErrorPage: (status, message) => ({ title: message }),
-	renderApp: (page, locale) => {
-		// render your app to HTML
-		return { html: "", head: "", css: "" };
+	getErrorPage(status, message) {
+		return {
+			id: `error-${status}`,
+			pageType: "error",
+			title: message,
+			statusCode: status,
+		};
+	},
+	renderApp(page, locale) {
+		// 这里接入你的 SSR 渲染函数
+		// 比如 Svelte 的 render() / ReactDOMServer / Vue SSR
+		void page;
+		void locale;
+		return {
+			html: "",
+			head: "",
+			css: "",
+		};
 	},
 });
+
 export { serializeServerData };
 ```
 
-`createSSRRender()` returns a `render(url, locale)` function compatible with the SSR module shape expected by `createServer()`.
+`createSSRRender()` 最终会生成一个：
 
-### HTML Template
+```ts
+(url: string, locale: string) => Promise<SSRRenderResult>
+```
 
-Your `index.html` must include SSR placeholders:
+这个签名正好就是 server / Vite 插件所需要的 SSR module 形状。
 
-```html
-<!DOCTYPE html>
-<html lang="<!--ssr-lang-->">
-	<head>
-		<!--ssr-head-->
-	</head>
-	<body>
-		<div id="app"><!--ssr-body--></div>
-		<!--ssr-data-->
-		<script type="module" src="/src/browser.ts"></script>
-	</body>
-</html>
+---
+
+### 第 6 步：如果你有 API 代理，写 `src/proxies.ts`
+
+```ts
+import type { Hono } from "hono";
+
+export default function setup(app: Hono) {
+	app.get("/api/health", (c) => c.json({ ok: true }));
+}
 ```
 
-| Placeholder       | Replaced with                              |
-| ----------------- | ------------------------------------------ |
-| `<!--ssr-lang-->` | Locale string (e.g. `en`)                  |
-| `<!--ssr-head-->` | `<head>` content + CSS                     |
-| `<!--ssr-body-->` | Server-rendered HTML                       |
-| `<!--ssr-data-->` | `<script>` tag with serialized server data |
+这里推荐导出 `default` 函数。
 
-These are also available as `SSR_PLACEHOLDERS.LANG`, `.HEAD`, `.BODY`, `.DATA` constants.
+`setup` 有两种传法：
 
-`injectSSRContent()` automatically wraps serialized server data in a `<script>` tag for the `<!--ssr-data-->` placeholder.
+- 传函数：只在 `dev` / `preview` 时可用
+- 传文件路径字符串：`dev` / `build` / `preview` / adapter 都可用
 
-## Common patterns
+如果你要部署到 adapter 环境里，**优先传文件路径字符串**。
 
-### Browser-only app
+---
 
-Use `startBrowserApp()` together with your framework mount callback. Browser bundlers will resolve the browser-only export automatically.
+### 第 7 步：配置 `vite.config.ts`
 
-### Full SSR app
+```ts
+import { finesoftFrontViteConfig } from "@finesoft/front";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [
+		finesoftFrontViteConfig({
+			locales: ["zh", "en"],
+			defaultLocale: "en",
+			ssr: { entry: "src/ssr.ts" },
+			setup: "src/proxies.ts",
+			adapter: "node",
+		}),
+	],
+});
+```
 
-Use the three pieces together:
+`adapter` 支持：
 
-1. `createServer()` — dev/prod server bootstrap
-2. `createSSRRender()` — SSR render function factory
-3. `startBrowserApp()` — client hydration
+- `"node"`
+- `"vercel"`
+- `"cloudflare"`
+- `"netlify"`
+- `"static"`
+- `"auto"`
+- 或者一个自定义 `Adapter` 对象
 
-## Selected exports
+---
 
-### Browser
+### 第 8 步：配置脚本
+
+```json
+{
+	"scripts": {
+		"dev": "vite",
+		"build": "vite build",
+		"preview": "vite preview"
+	}
+}
+```
+
+---
+
+### 第 9 步：启动项目
+
+```bash
+pnpm dev
+```
+
+构建：
+
+```bash
+pnpm build
+```
+
+本地 SSR 预览：
+
+```bash
+pnpm preview
+```
+
+---
+
+## Adapter 指南：构建后到底会产出什么
+
+这一节非常重要，因为很多人一到部署阶段就开始“咦，我文件呢？”。
+
+### `adapter: "node"`
+
+输出：
+
+- `dist/server/index.mjs`
+
+运行方式：
+
+```bash
+node dist/server/index.mjs
+```
+
+适合：
+
+- 自己管 Node 进程
+- Docker
+- VPS
+- PM2
+
+---
+
+### `adapter: "vercel"`
+
+输出：
+
+- `.vercel/output/config.json`
+- `.vercel/output/static/`
+- `.vercel/output/functions/ssr.func/`
+
+注意：
 
--   `startBrowserApp`
--   `History`
--   `registerActionHandlers`
--   `registerExternalUrlHandler`
--   `registerFlowActionHandler`
--   `deserializeServerData`
--   `createPrefetchedIntentsFromDom`
--   `tryScroll`
+- **它不在 `dist/` 里面，这是正常的**
+- 这是 Vercel Build Output API v3 的约定目录
+- 不是框架任性，是平台规定就这么放
+
+建议把 `.vercel/` 加进 `.gitignore`
+
+---
+
+### `adapter: "netlify"`
+
+输出：
+
+- `.netlify/functions-internal/ssr/index.mjs`
+- `dist/client/_redirects`
+
+注意：
+
+- **`.netlify/` 在 `dist/` 外面也是正常的**
+- 这是 Netlify Functions 的约定目录
+- 真正的 publish 目录通常是 `dist/client/`
+
+同样建议把 `.netlify/` 加进 `.gitignore`
+
+---
+
+### `adapter: "cloudflare"`
+
+输出：
+
+- `dist/cloudflare/_worker.js`
+- `dist/cloudflare/assets/`
+
+注意：
+
+- Cloudflare Workers 环境不是完整 Node.js
+- 如果你的 `setup` 或运行时代码依赖 Node API，可能需要 `nodejs_compat`
+
+---
+
+### `adapter: "static"`
+
+输出：
+
+- `dist/static/`
+
+适合：
+
+- 纯静态托管
+- CDN / OSS / Pages
+- 不依赖运行时服务端逻辑的页面
+
+它会做的事：
+
+1. 从你的 `routes` 导出中读取路由
+2. 自动预渲染**无参数路由**
+3. 复制客户端静态资源
+4. 输出纯 HTML/CSS/JS 站点
+
+#### `static` 模式的三个重要限制
+
+##### 1）只会自动预渲染无参数路由
+
+比如这些会自动生成：
+
+- `/`
+- `/search`
+- `/games`
+
+这些不会自动生成：
+
+- `/product/:id`
+- `/list/:category`
+
+如果你要预渲染动态 URL，请补充具体地址，例如：
+
+```ts
+import { staticAdapter } from "@finesoft/front";
+
+finesoftFrontViteConfig({
+	adapter: staticAdapter({
+		dynamicRoutes: ["/product/123", "/list/games"],
+	}),
+});
+```
+
+##### 2）构建时必须能拿到页面数据
+
+`static` 预渲染是**构建期执行 Controller**。
+
+这意味着：
+
+- 如果你的 Controller 会 `fetch` API
+- 而构建时没有 API 服务
+- 那么页面就会渲染失败或退化成错误页
+
+解决方式有两个：
+
+- 构建时保证 API 可访问
+- 给 Controller 的 `fallback()` 提供 mock 数据回退
+
+##### 3）预览静态产物时，要看的是 `dist/static/`
+
+`vite preview` 更适合看标准 Vite 构建产物和 SSR 预览。
+
+如果你要验证 `static` 最终结果，请直接服务 `dist/static/`，例如：
+
+```bash
+cd dist/static
+python3 -m http.server 3000
+```
+
+---
+
+### `adapter: "auto"`
+
+会根据环境变量自动选择：
+
+- `VERCEL` → `vercel`
+- `CF_PAGES` → `cloudflare`
+- `NETLIFY` → `netlify`
+- 默认 → `node`
+
+适合 CI / 平台自动识别场景。
+
+---
+
+## 如果你想自己写 Adapter
+
+可以直接传对象：
+
+```ts
+import type { Adapter } from "@finesoft/front";
+
+const customAdapter: Adapter = {
+	name: "my-platform",
+	async build(ctx) {
+		// ctx 里有 root / vite / fs / path / templateHtml
+		// 也有 generateSSREntry / buildBundle / copyStaticAssets 等工具
+	},
+};
+```
+
+然后：
+
+```ts
+finesoftFrontViteConfig({
+	adapter: customAdapter,
+});
+```
+
+---
+
+## 手动模式：直接用 `createServer()`
+
+如果你不想依赖 Vite 插件，也可以直接起服务器。
+
+```ts
+import { createServer } from "@finesoft/front";
+
+const { app, vite, runtime } = await createServer({
+	root: process.cwd(),
+	locales: ["zh", "en"],
+	defaultLocale: "en",
+	port: 3000,
+	setup(app) {
+		app.get("/api/health", (c) => c.json({ ok: true }));
+	},
+	ssr: {
+		ssrEntryPath: "/src/ssr.ts",
+	},
+});
+
+void app;
+void vite;
+void runtime;
+```
+
+### `createServer()` 会帮你做什么
+
+1. 解析根目录
+2. 如果存在 `.env`，尝试加载它
+3. 检测当前运行时
+4. 开发模式下创建 Vite middleware server
+5. 创建 Hono app
+6. 先挂你的业务路由
+7. 再挂 SSR catch-all
+8. 启动服务
+
+### `createServer()` 默认行为
+
+- `root` 默认是 `process.cwd()`
+- `port` 默认是 `process.env.PORT ?? 3000`
+- 如果根目录存在 `.env` 且安装了 `dotenv`，会自动尝试加载
+
+---
+
+## 纯浏览器模式
+
+如果你只想要 Framework / Router / Action / Controller，不做 SSR，也能单独使用。
+
+```ts
+import { Framework, defineRoutes, startBrowserApp } from "@finesoft/front";
+
+function bootstrap(framework: Framework) {
+	defineRoutes(framework, [
+		{ path: "/", intentId: "home", controller: new HomeController() },
+	]);
+}
+
+startBrowserApp({
+	bootstrap,
+	mount: (target) => {
+		return ({ page }) => {
+			void target;
+			void page;
+		};
+	},
+	callbacks: {
+		onNavigate() {},
+		onModal() {},
+	},
+});
+```
+
+---
+
+## 你最常会用到的 API
+
+### 路由与 Intent
+
+- `defineRoutes()`：声明式注册路由
+- `Framework.routeUrl()`：把 URL 匹配成 Intent
+- `Framework.dispatch()`：执行 Intent
+- `BaseController`：页面控制器基类
+
+### 浏览器启动
+
+- `startBrowserApp()`：一站式 hydration 启动
+- `registerActionHandlers()`：注册 action handlers
+- `History`：浏览器导航状态管理
 
 ### SSR
 
--   `createSSRRender`
--   `ssrRender`
--   `injectSSRContent`
--   `serializeServerData`
--   `SSR_PLACEHOLDERS`
-
-### Server
-
--   `createServer`
--   `createSSRApp`
--   `startServer`
--   `parseAcceptLanguage`
--   `detectRuntime`
--   `resolveRoot`
-
-## API Overview
-
-| Category | Key Exports                                                                     |
-| -------- | ------------------------------------------------------------------------------- |
-| Core     | `Framework`, `Router`, `Container`, `defineRoutes`, `BaseController`            |
-| Actions  | `ActionDispatcher`, `isFlowAction`, `isExternalUrlAction`, `makeFlowAction`     |
-| HTTP     | `HttpClient`, `HttpError`                                                       |
-| Browser  | `startBrowserApp`, `History`, `registerActionHandlers`, `deserializeServerData` |
-| SSR      | `createSSRRender`, `ssrRender`, `serializeServerData`, `injectSSRContent`       |
-| Server   | `createServer`, `createSSRApp`, `startServer`, `parseAcceptLanguage`            |
-| Utils    | `LruMap`, `buildUrl`, `pipe`, `pipeAsync`, `mapEach`                            |
+- `createSSRRender()`：生成 `render(url, locale)`
+- `serializeServerData()`：序列化服务端数据
+- `injectSSRContent()`：把 SSR 内容注入 HTML 模板
+
+### 服务端 / 部署
+
+- `createServer()`：手动启动 SSR 服务
+- `finesoftFrontViteConfig()`：推荐用的 Vite 插件入口
+- `nodeAdapter()` / `vercelAdapter()` / `cloudflareAdapter()` / `netlifyAdapter()` / `staticAdapter()` / `autoAdapter()`
+
+---
+
+## 常见坑位（强烈建议先看）
+
+### 1. `index.html` 没放 SSR 占位符
+
+症状：
+
+- 页面不 hydrate
+- SSR 内容丢失
+- server data 不进页面
+
+解决：检查这四个占位符是否都在：
+
+- `<!--ssr-lang-->`
+- `<!--ssr-head-->`
+- `<!--ssr-body-->`
+- `<!--ssr-data-->`
+
+---
+
+### 2. `setup` 传了函数，但部署产物里没有生效
+
+原因：
+
+- 直接传函数只适合 `dev/preview`
+- adapter 构建期没法可靠地把内联函数带进去
+
+解决：
+
+- 用文件路径字符串，例如 `setup: "src/proxies.ts"`
+
+---
+
+### 3. `static` 模式下动态路由没有页面
+
+原因：
+
+- `staticAdapter()` 只会自动预渲染无参数路由
+
+解决：
+
+- 用 `dynamicRoutes` 传入具体 URL
+
+---
+
+### 4. `static` 模式构建出来是 500 错误页
+
+原因：
+
+- 构建时 Controller 调 API 失败
+- 但 `fallback()` 只返回错误页，没有 mock 数据
+
+解决：
+
+- 构建时保证 API 可访问，或者
+- 给 Controller 增加 mock fallback
+
+---
+
+### 5. `.vercel/` 和 `.netlify/` 为什么不在 `dist/`
+
+答案：
+
+- **这是平台规范，不是 bug**
+- Vercel 要求 `.vercel/output/`
+- Netlify 要求 `.netlify/functions-internal/`
+
+建议：
+
+- 把它们加入 `.gitignore`
+
+---
+
+## 一个更完整的推荐心智模型
+
+你可以把它理解成下面这条链路：
+
+$$
+URL \rightarrow Router \rightarrow Intent \rightarrow Controller \rightarrow Page\ Model \rightarrow SSR / Browser\ UI
+$$
+
+也就是说：
+
+- URL 负责定位页面语义
+- Intent 负责描述“我要什么页面”
+- Controller 负责拉数据和组装页面模型
+- UI 层只负责把 `Page` 渲染出来
+
+这也是这套框架最值钱的地方：**页面逻辑和 UI 框架解耦**。
+
+---
+
+## 最后给一个实战建议
+
+如果你第一次接这个包，建议按下面顺序推进：
+
+1. 先只做一个 `/` 首页
+2. 跑通 `browser.ts` + `ssr.ts` + `index.html`
+3. 再接 `finesoftFrontViteConfig()`
+4. 开发阶段先用 `adapter: "node"`
+5. 最后再切 `vercel` / `netlify` / `cloudflare` / `static`
+
+别一上来就同时搞多语言、动态路由、SSR、静态预渲染、平台部署。那样很容易把自己卷成一个调试陀螺。
+
+---
 
 ## License