isr-engine 2.6.21 → 3.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +97 -616
- package/dist/Logger-DqBS_3v8.cjs +184 -0
- package/dist/Logger-DqBS_3v8.cjs.map +1 -0
- package/dist/Logger-bg-doGwZ.js +174 -0
- package/dist/Logger-bg-doGwZ.js.map +1 -0
- package/dist/abVariantContext-BvAMuhjj.cjs +510 -0
- package/dist/abVariantContext-BvAMuhjj.cjs.map +1 -0
- package/dist/abVariantContext-Ud3aZ1yk.js +355 -0
- package/dist/abVariantContext-Ud3aZ1yk.js.map +1 -0
- package/dist/app/createISRApp.d.ts +2 -2
- package/dist/cli/cli.cjs +1 -1
- package/dist/cli/cli.js +1 -1
- package/dist/cli/start.d.ts +1 -1
- package/dist/config/loadConfig.d.ts +1 -1
- package/dist/config/normalizeEngineConfig.d.ts +1 -1
- package/dist/config/normalizeEngineConfig.d.ts.map +1 -1
- package/dist/config/resolveRuntimeRedis.d.ts +1 -1
- package/dist/{createCacheInspectorMiddleware-DYJ2WGYu.js → createCacheInspectorMiddleware-Bjku5v62.js} +10 -5
- package/dist/createCacheInspectorMiddleware-Bjku5v62.js.map +1 -0
- package/dist/{createCacheInspectorMiddleware-Byzz8ZlU.cjs → createCacheInspectorMiddleware-DG1_VLBS.cjs} +12 -5
- package/dist/createCacheInspectorMiddleware-DG1_VLBS.cjs.map +1 -0
- package/dist/{createISRApp-CylUYiIU.js → createISRApp-DYVU8ydT.js} +632 -100
- package/dist/createISRApp-DYVU8ydT.js.map +1 -0
- package/dist/{createISRApp-C9Bezuit.cjs → createISRApp-HX6X8UNb.cjs} +698 -129
- package/dist/createISRApp-HX6X8UNb.cjs.map +1 -0
- package/dist/{createImagePlugin-_ntL0DcT.js → createImagePlugin-BZJHOvN9.js} +67 -21
- package/dist/createImagePlugin-BZJHOvN9.js.map +1 -0
- package/dist/{createImagePlugin-birVNynL.cjs → createImagePlugin-Ca4t_WhM.cjs} +73 -21
- package/dist/createImagePlugin-Ca4t_WhM.cjs.map +1 -0
- package/dist/defaults/runtime/browserObservability.d.ts.map +1 -1
- package/dist/defaults/runtime/defineSiteHooks.cjs +2 -2
- package/dist/defaults/runtime/defineSiteHooks.js +2 -2
- package/dist/defaults/runtime/dev-style-resource-dispatcher.server.d.ts.map +1 -1
- package/dist/{defineSiteHooks-BeVy-qPH.js → defineSiteHooks-CV4tqHvB.js} +11 -5
- package/dist/{defineSiteHooks-BeVy-qPH.js.map → defineSiteHooks-CV4tqHvB.js.map} +1 -1
- package/dist/{defineSiteHooks-C3v3WLS8.cjs → defineSiteHooks-w2IrF5-D.cjs} +11 -5
- package/dist/{defineSiteHooks-C3v3WLS8.cjs.map → defineSiteHooks-w2IrF5-D.cjs.map} +1 -1
- package/dist/engine/ISREngine.d.ts +2 -2
- package/dist/engine/ISREngine.d.ts.map +1 -1
- package/dist/{i18n-CyJIoYJT.cjs → i18n-CS5QhOO0.cjs} +7 -30
- package/dist/i18n-CS5QhOO0.cjs.map +1 -0
- package/dist/{i18n-Dobe0Wxn.js → i18n-CnXYAgQE.js} +8 -25
- package/dist/i18n-CnXYAgQE.js.map +1 -0
- package/dist/index.d.ts +3 -3
- package/dist/isr/ISRRoutes.d.ts +5 -3
- package/dist/isr/ISRRoutes.d.ts.map +1 -1
- package/dist/isr-engine.cjs +619 -117
- package/dist/isr-engine.cjs.map +1 -1
- package/dist/isr-engine.js +609 -107
- package/dist/isr-engine.js.map +1 -1
- package/dist/logger/Logger.d.ts +6 -2
- package/dist/logger/Logger.d.ts.map +1 -1
- package/dist/logger/logRecord.d.ts +11 -0
- package/dist/logger/logRecord.d.ts.map +1 -0
- package/dist/logger/runtimeLogger.d.ts +6 -0
- package/dist/logger/runtimeLogger.d.ts.map +1 -0
- package/dist/metrics/PromMetrics.d.ts.map +1 -1
- package/dist/middlewares/LocaleRedirect.d.ts.map +1 -1
- package/dist/plugin/createCacheInspectorMiddleware.d.ts.map +1 -1
- package/dist/plugin/createDevCssHandoffPlugin.d.ts.map +1 -1
- package/dist/plugin/createFontPlugin.d.ts +1 -1
- package/dist/plugin/createFontPlugin.d.ts.map +1 -1
- package/dist/plugin/createIsrPlugin.d.ts.map +1 -1
- package/dist/plugin/googleFontAssets.d.ts +23 -0
- package/dist/plugin/googleFontAssets.d.ts.map +1 -0
- package/dist/plugin/isrCacheMiddleware.d.ts +5 -0
- package/dist/plugin/isrCacheMiddleware.d.ts.map +1 -1
- package/dist/plugin/remoteImageSource.d.ts +3 -3
- package/dist/plugin/remoteImageSource.d.ts.map +1 -1
- package/dist/rsc/ServerActions.d.ts.map +1 -1
- package/dist/rsc/cacheTag.d.ts.map +1 -1
- package/dist/rsc/index.cjs +8 -9
- package/dist/rsc/index.js +2 -3
- package/dist/rsc/revalidate.d.ts.map +1 -1
- package/dist/rsc/revalidationMetrics.d.ts +6 -0
- package/dist/rsc/revalidationMetrics.d.ts.map +1 -0
- package/dist/{rsc-lvWPTuVD.js → rsc-BJzB9s8U.js} +4 -6
- package/dist/rsc-BJzB9s8U.js.map +1 -0
- package/dist/{rsc-H7D_meHu.cjs → rsc-CYT6B6bf.cjs} +5 -7
- package/dist/rsc-CYT6B6bf.cjs.map +1 -0
- package/dist/server/manager.d.ts +1 -1
- package/dist/server/manager.d.ts.map +1 -1
- package/dist/server/opsConfig.d.ts +7 -1
- package/dist/server/opsConfig.d.ts.map +1 -1
- package/dist/server/productionRuntime.d.ts +3 -4
- package/dist/server/productionRuntime.d.ts.map +1 -1
- package/dist/server/requestLimits.d.ts +36 -0
- package/dist/server/requestLimits.d.ts.map +1 -0
- package/dist/server/safeRedirect.d.ts +6 -0
- package/dist/server/safeRedirect.d.ts.map +1 -0
- package/dist/server/types.d.ts +1 -1
- package/dist/ssg/spider.d.ts.map +1 -1
- package/dist/types/ISRConfig.d.ts +17 -0
- package/dist/types/ISRConfig.d.ts.map +1 -1
- package/dist/utils/cookie.d.ts.map +1 -1
- package/dist/utils/resolveFetchHandler.d.ts.map +1 -1
- package/package.json +30 -32
- package/src/defaults/runtime/browserObservability.ts +29 -13
- package/src/defaults/runtime/defineServerEntry.tsx +2 -2
- package/src/defaults/runtime/defineSiteHooks.ts +12 -7
- package/src/defaults/runtime/dev-style-resource-dispatcher.server.ts +2 -3
- package/src/types/ISRConfig.ts +21 -7
- package/src/utils/cookie.ts +5 -3
- package/src/utils/resolveFetchHandler.ts +1 -3
- package/dist/RequestContext-BVQ-rOmV.js +0 -58
- package/dist/RequestContext-BVQ-rOmV.js.map +0 -1
- package/dist/RequestContext-DgGEAxcW.cjs +0 -105
- package/dist/RequestContext-DgGEAxcW.cjs.map +0 -1
- package/dist/abVariantContext-CWCdRSdG.js +0 -549
- package/dist/abVariantContext-CWCdRSdG.js.map +0 -1
- package/dist/abVariantContext-Cqp-uxtd.cjs +0 -678
- package/dist/abVariantContext-Cqp-uxtd.cjs.map +0 -1
- package/dist/createCacheInspectorMiddleware-Byzz8ZlU.cjs.map +0 -1
- package/dist/createCacheInspectorMiddleware-DYJ2WGYu.js.map +0 -1
- package/dist/createISRApp-C9Bezuit.cjs.map +0 -1
- package/dist/createISRApp-CylUYiIU.js.map +0 -1
- package/dist/createImagePlugin-_ntL0DcT.js.map +0 -1
- package/dist/createImagePlugin-birVNynL.cjs.map +0 -1
- package/dist/i18n-CyJIoYJT.cjs.map +0 -1
- package/dist/i18n-Dobe0Wxn.js.map +0 -1
- package/dist/rsc-H7D_meHu.cjs.map +0 -1
- package/dist/rsc-lvWPTuVD.js.map +0 -1
package/README.md
CHANGED
|
@@ -1,695 +1,176 @@
|
|
|
1
|
-
#
|
|
1
|
+
# isr-engine
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
基于 Vite 与 React Server Components 的页面渲染编排层,提供按路由配置的 ISR、SSG、SSR、缓存失效和渲染失败恢复。Flight 编译与传输由 `@vitejs/plugin-rsc` 处理。
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## 运行要求与安装
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
7
|
+
- Node.js **24.15.0**;仓库使用 pnpm 9.15.9。
|
|
8
|
+
- TypeScript **6.0.3**;`paths` 相对声明它的配置文件解析,不再设置 `baseUrl`。
|
|
9
|
+
- Vite **8.1.6**;引擎内置 `@vitejs/plugin-rsc` **0.5.39** 及其 Flight 运行时。
|
|
10
|
+
- React 与 React DOM 使用正式版 **19.3.1**。引擎管理 HTML 流传输依赖。
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
> 包名前缀 `@novel-isr` 仅是首发项目代号,与小说业务**无任何耦合**——
|
|
14
|
-
> grep 全仓源码无业务硬编码,运行时无业务假设。发到 GitHub Packages
|
|
15
|
-
> (restricted),不发 public registry;项目仍处于 **alpha** 阶段(详见末尾「生产可用性诚实评估」)。
|
|
16
|
-
|
|
17
|
-
## 30 秒看明白
|
|
12
|
+
在应用目录安装引擎和应用直接使用的 React、Vite:
|
|
18
13
|
|
|
19
14
|
```bash
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
react@19.3.0-canary-bd6ea412-20260824 \
|
|
24
|
-
react-dom@19.3.0-canary-bd6ea412-20260824 \
|
|
25
|
-
react-server-dom-webpack@19.3.0-canary-bd6ea412-20260824 \
|
|
26
|
-
rsc-html-stream
|
|
27
|
-
pnpm add -D vite typescript @types/react @types/react-dom
|
|
15
|
+
npm install --save-exact isr-engine react@19.3.1 react-dom@19.3.1
|
|
16
|
+
npm install --save-dev --save-exact vite@8.1.6 typescript@6.0.3 \
|
|
17
|
+
@types/node@24.19.2 @types/react@19.2.15 @types/react-dom@19.2.3
|
|
28
18
|
```
|
|
29
19
|
|
|
30
|
-
|
|
20
|
+
应用 `package.json` 设置 `"type": "module"`,并保留锁文件以复现依赖组合。
|
|
21
|
+
|
|
22
|
+
## 最小应用
|
|
31
23
|
|
|
32
|
-
|
|
24
|
+
`vite.config.ts`:
|
|
33
25
|
|
|
34
26
|
```ts
|
|
35
|
-
// vite.config.ts
|
|
36
27
|
import { defineConfig } from 'vite';
|
|
37
|
-
import { createIsrPlugin } from '
|
|
38
|
-
export default defineConfig({ plugins: [...createIsrPlugin()] });
|
|
39
|
-
```
|
|
28
|
+
import { createIsrPlugin } from 'isr-engine';
|
|
40
29
|
|
|
41
|
-
|
|
42
|
-
// package.json
|
|
43
|
-
{
|
|
44
|
-
"scripts": {
|
|
45
|
-
"dev": "novel-isr dev",
|
|
46
|
-
"build": "vite build",
|
|
47
|
-
"start": "novel-isr start"
|
|
48
|
-
}
|
|
49
|
-
}
|
|
30
|
+
export default defineConfig({ plugins: [...createIsrPlugin()] });
|
|
50
31
|
```
|
|
51
32
|
|
|
52
|
-
|
|
53
|
-
// src/routes.tsx —— 业务唯一路由源;SSR/ISR/SSG/CSR recovery 都复用这一份
|
|
54
|
-
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
55
|
-
|
|
56
|
-
export const { routes } = defineRoutes({
|
|
57
|
-
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
58
|
-
routes: [
|
|
59
|
-
{ path: '/', load: () => import('./pages/HomePage') },
|
|
60
|
-
{ path: '/books/:id', load: () => import('./pages/BookDetailPage') },
|
|
61
|
-
{ path: '/about', load: () => import('./pages/AboutPage') },
|
|
62
|
-
],
|
|
63
|
-
});
|
|
64
|
-
```
|
|
33
|
+
`src/app.tsx` 是应用根 Server Component,必须命名导出 `App`。交互组件单独使用 `'use client'`:
|
|
65
34
|
|
|
66
35
|
```tsx
|
|
67
|
-
|
|
68
|
-
import { parseLocale, resolveI18nConfig } from '@novel-isr/engine/runtime';
|
|
69
|
-
import siteHooks from './entry.server';
|
|
70
|
-
import { routes } from './routes';
|
|
71
|
-
|
|
72
|
-
const I18N = resolveI18nConfig(siteHooks.intl);
|
|
36
|
+
import { cacheTag } from 'isr-engine/rsc';
|
|
73
37
|
|
|
74
38
|
export function App({ url }: { url: URL }) {
|
|
75
|
-
|
|
39
|
+
cacheTag('site-content');
|
|
76
40
|
return (
|
|
77
|
-
<html lang=
|
|
78
|
-
<
|
|
41
|
+
<html lang="zh-CN">
|
|
42
|
+
<head><meta charSet="utf-8" /><title>My site</title></head>
|
|
43
|
+
<body><main><h1>{url.pathname}</h1></main></body>
|
|
79
44
|
</html>
|
|
80
45
|
);
|
|
81
46
|
}
|
|
82
47
|
```
|
|
83
48
|
|
|
49
|
+
项目根目录的 `ssr.config.ts` 声明渲染策略与部署配置:
|
|
50
|
+
|
|
84
51
|
```ts
|
|
85
|
-
|
|
86
|
-
import { defineIsrConfig } from '@novel-isr/engine/config';
|
|
87
|
-
import fallbackLocal from './src/config/site-fallback-local.json';
|
|
52
|
+
import { defineIsrConfig } from 'isr-engine/config';
|
|
88
53
|
|
|
89
54
|
export default defineIsrConfig({
|
|
90
55
|
renderMode: 'isr',
|
|
91
|
-
|
|
92
|
-
site: process.env.SITE_URL ?? 'http://localhost:3000',
|
|
93
|
-
services: {
|
|
94
|
-
api: process.env.API_URL ?? 'http://localhost:8080',
|
|
95
|
-
telemetry: process.env.TELEMETRY_API_URL ?? process.env.API_URL ?? 'http://localhost:8080',
|
|
96
|
-
},
|
|
97
|
-
redis: {
|
|
98
|
-
url: process.env.REDIS_URL,
|
|
99
|
-
host: undefined,
|
|
100
|
-
port: undefined,
|
|
101
|
-
password: undefined,
|
|
102
|
-
keyPrefix: 'isr:',
|
|
103
|
-
invalidationChannel: 'isr:invalidate',
|
|
104
|
-
},
|
|
105
|
-
telemetry: {
|
|
106
|
-
app: 'novel-rating',
|
|
107
|
-
release: process.env.APP_VERSION,
|
|
108
|
-
environment: process.env.NODE_ENV,
|
|
109
|
-
includeQueryString: false,
|
|
110
|
-
events: {
|
|
111
|
-
endpoint: '/api/observability/analytics',
|
|
112
|
-
trackInitialPage: true,
|
|
113
|
-
sampleRate: 1,
|
|
114
|
-
batchSize: 20,
|
|
115
|
-
flushIntervalMs: 3000,
|
|
116
|
-
maxQueueSize: 500,
|
|
117
|
-
retryBaseDelayMs: 1000,
|
|
118
|
-
retryMaxDelayMs: 30000,
|
|
119
|
-
},
|
|
120
|
-
errors: {
|
|
121
|
-
endpoint: '/api/observability/errors',
|
|
122
|
-
captureResourceErrors: true,
|
|
123
|
-
sampleRate: 1,
|
|
124
|
-
batchSize: 10,
|
|
125
|
-
flushIntervalMs: 3000,
|
|
126
|
-
maxQueueSize: 200,
|
|
127
|
-
retryBaseDelayMs: 1000,
|
|
128
|
-
retryMaxDelayMs: 30000,
|
|
129
|
-
},
|
|
130
|
-
webVitals: { enabled: true },
|
|
131
|
-
exporters: [],
|
|
132
|
-
integrations: {
|
|
133
|
-
sentry: {
|
|
134
|
-
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
135
|
-
dsn: process.env.SENTRY_DSN,
|
|
136
|
-
tracesSampleRate: 0.1,
|
|
137
|
-
environment: process.env.NODE_ENV,
|
|
138
|
-
release: process.env.APP_VERSION,
|
|
139
|
-
},
|
|
140
|
-
},
|
|
141
|
-
},
|
|
142
|
-
experiments: {
|
|
143
|
-
'hero-style': { variants: ['classic', 'bold'], weights: [50, 50] },
|
|
144
|
-
},
|
|
145
|
-
i18n: {
|
|
146
|
-
locales: fallbackLocal.site.locales,
|
|
147
|
-
defaultLocale: fallbackLocal.site.defaultLocale,
|
|
148
|
-
prefixDefault: false,
|
|
149
|
-
endpoint: '/api/i18n/{locale}/manifest',
|
|
150
|
-
fallbackLocal: fallbackLocal.i18n.strings,
|
|
151
|
-
ttl: 60_000,
|
|
152
|
-
timeoutMs: 1200,
|
|
153
|
-
remoteSource: 'admin-server',
|
|
154
|
-
fallbackSource: 'fallback-local',
|
|
155
|
-
},
|
|
156
|
-
seo: {
|
|
157
|
-
endpoint: '/api/seo?path={pathname}',
|
|
158
|
-
fallbackLocal: fallbackLocal.seo.entries,
|
|
159
|
-
ttl: 60_000,
|
|
160
|
-
timeoutMs: 1200,
|
|
161
|
-
},
|
|
162
|
-
},
|
|
56
|
+
revalidate: 60,
|
|
163
57
|
routes: {
|
|
164
58
|
'/': { mode: 'isr', ttl: 60, staleWhileRevalidate: 300 },
|
|
165
59
|
'/about': 'ssg',
|
|
166
|
-
'/
|
|
167
|
-
|
|
60
|
+
'/account/*': 'ssr',
|
|
61
|
+
},
|
|
62
|
+
runtime: {
|
|
63
|
+
site: process.env.SITE_URL ?? 'http://localhost:3000',
|
|
64
|
+
services: { api: undefined, telemetry: undefined },
|
|
65
|
+
redis: process.env.REDIS_URL ? {
|
|
66
|
+
url: process.env.REDIS_URL,
|
|
67
|
+
host: undefined, port: undefined, password: undefined,
|
|
68
|
+
keyPrefix: 'my-site:', invalidationChannel: 'my-site:invalidate',
|
|
69
|
+
} : undefined,
|
|
70
|
+
experiments: {},
|
|
71
|
+
i18n: undefined, seo: undefined, telemetry: false,
|
|
168
72
|
},
|
|
169
73
|
server: {
|
|
170
74
|
port: Number(process.env.PORT ?? 3000),
|
|
171
75
|
host: process.env.HOST,
|
|
172
|
-
strictPort: process.env.NODE_ENV
|
|
76
|
+
strictPort: process.env.NODE_ENV === 'production',
|
|
173
77
|
ops: {
|
|
174
78
|
authToken: process.env.ISR_OPS_TOKEN,
|
|
175
79
|
tokenHeader: 'x-isr-admin-token',
|
|
176
80
|
health: { enabled: true, public: true },
|
|
177
81
|
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
82
|
+
inventory: { enabled: true, public: false },
|
|
178
83
|
},
|
|
179
84
|
},
|
|
180
85
|
ssg: {
|
|
181
|
-
routes: ['/about'],
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
maxRetries: 3,
|
|
185
|
-
retryBaseDelayMs: 200,
|
|
186
|
-
failBuildThreshold: 0.05,
|
|
187
|
-
},
|
|
188
|
-
revalidate: 3600,
|
|
189
|
-
});
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
```ts
|
|
193
|
-
// src/entry.server.ts —— 可选:只放请求期 hooks,例如用户、租户、分层、错误上报
|
|
194
|
-
import { defineAdminSiteHooks, readCookie } from '@novel-isr/engine/site-hooks';
|
|
195
|
-
|
|
196
|
-
export default defineAdminSiteHooks({
|
|
197
|
-
beforeRequest: req => ({
|
|
198
|
-
userId: req.headers.get('x-user-id') ?? readCookie(req, 'uid') ?? undefined,
|
|
199
|
-
tenantId: req.headers.get('x-tenant-id') ?? 'public',
|
|
200
|
-
}),
|
|
201
|
-
onError: (err, req, ctx) => {
|
|
202
|
-
console.error('[render error]', { traceId: ctx.traceId, url: req.url, err });
|
|
86
|
+
routes: ['/about'], concurrent: 3,
|
|
87
|
+
requestTimeoutMs: 30_000, maxRetries: 3,
|
|
88
|
+
retryBaseDelayMs: 200, failBuildThreshold: 0.05,
|
|
203
89
|
},
|
|
204
90
|
});
|
|
205
91
|
```
|
|
206
92
|
|
|
207
|
-
`
|
|
208
|
-
`getRequestContext()` 读取用户、租户、分群等请求级字段;Client Component 需要由
|
|
209
|
-
Server Component 读取后作为 props 传入。A/B variant 不在 `beforeRequest` 里手写解析,
|
|
210
|
-
页面用 `getVariant()` 读取,engine 负责 sticky cookie 和 ISR variant 缓存隔离。
|
|
211
|
-
完整用法见 [docs/site-hooks.md](./docs/site-hooks.md#beforerequest--onerror)。
|
|
212
|
-
|
|
213
|
-
`pnpm dev` → http://localhost:3000。开发模式会自动注入 **Novel ISR Inspector** 浮层,
|
|
214
|
-
可直接切换/验证 ISR、SSR、SSG、CSR fallback。业务不需要 import 调试组件。
|
|
215
|
-
如需隐藏浮层,新建 `src/entry.tsx`:
|
|
216
|
-
|
|
217
|
-
```ts
|
|
218
|
-
export default {
|
|
219
|
-
devInspector: false,
|
|
220
|
-
};
|
|
221
|
-
```
|
|
222
|
-
|
|
223
|
-
浏览器埋点和错误上报由 engine 按 endpoint 配置注入轻量 runtime,业务不用重写导航监听或全局错误监听,
|
|
224
|
-
也不需要把第三方 SDK import 到 engine。部署期只在 `ssr.config.ts` 配 telemetry endpoint、
|
|
225
|
-
采样、批量策略和 integration:
|
|
226
|
-
|
|
227
|
-
```ts
|
|
228
|
-
// ssr.config.ts
|
|
229
|
-
export default {
|
|
230
|
-
runtime: {
|
|
231
|
-
services: {
|
|
232
|
-
api: process.env.API_URL ?? 'https://admin.example.com',
|
|
233
|
-
telemetry: process.env.TELEMETRY_API_URL ?? 'https://admin.example.com',
|
|
234
|
-
},
|
|
235
|
-
telemetry: {
|
|
236
|
-
app: 'novel-rating',
|
|
237
|
-
release: process.env.APP_VERSION,
|
|
238
|
-
environment: process.env.NODE_ENV,
|
|
239
|
-
includeQueryString: false,
|
|
240
|
-
events: {
|
|
241
|
-
endpoint: '/api/observability/analytics',
|
|
242
|
-
trackInitialPage: true,
|
|
243
|
-
sampleRate: 1,
|
|
244
|
-
batchSize: 20,
|
|
245
|
-
flushIntervalMs: 3000,
|
|
246
|
-
maxQueueSize: 500,
|
|
247
|
-
retryBaseDelayMs: 1000,
|
|
248
|
-
retryMaxDelayMs: 30000,
|
|
249
|
-
},
|
|
250
|
-
errors: {
|
|
251
|
-
endpoint: '/api/observability/errors',
|
|
252
|
-
captureResourceErrors: true,
|
|
253
|
-
sampleRate: 1,
|
|
254
|
-
batchSize: 10,
|
|
255
|
-
flushIntervalMs: 3000,
|
|
256
|
-
maxQueueSize: 200,
|
|
257
|
-
retryBaseDelayMs: 1000,
|
|
258
|
-
retryMaxDelayMs: 30000,
|
|
259
|
-
},
|
|
260
|
-
webVitals: { enabled: true },
|
|
261
|
-
exporters: [],
|
|
262
|
-
integrations: {
|
|
263
|
-
sentry: {
|
|
264
|
-
enabled: process.env.SENTRY_ENABLED === 'true',
|
|
265
|
-
dsn: process.env.SENTRY_DSN,
|
|
266
|
-
tracesSampleRate: 0.1,
|
|
267
|
-
environment: process.env.NODE_ENV,
|
|
268
|
-
release: process.env.APP_VERSION,
|
|
269
|
-
},
|
|
270
|
-
},
|
|
271
|
-
},
|
|
272
|
-
},
|
|
273
|
-
};
|
|
274
|
-
```
|
|
275
|
-
|
|
276
|
-
设计边界:`isr-engine` 不 import 业务 SDK,也不绑定 Sentry/Datadog/自研采集端;
|
|
277
|
-
第一方 HTTP 链路只看 `events.endpoint` / `errors.endpoint`,不再在 exporter 里重复配置同一个地址。
|
|
278
|
-
Sentry 是
|
|
279
|
-
`runtime.telemetry.integrations.sentry` 里的完整第三方平台集成,不降级成普通 HTTP exporter;
|
|
280
|
-
它可和第一方 endpoint 同时使用,也可通过关闭 `events/errors` 做二选一。
|
|
281
|
-
engine 不做隐式替换,失败不会影响渲染或其它上报。
|
|
282
|
-
`@novel-isr/analytics` 和 `@novel-isr/error-reporting`
|
|
283
|
-
是独立 SDK,给非 engine 应用或自定义集成使用。
|
|
284
|
-
完整说明见 [docs/observability.md](./docs/observability.md)。
|
|
285
|
-
|
|
286
|
-
业务显式事件不要写 endpoint 上传逻辑,直接用 engine runtime facade:
|
|
287
|
-
|
|
288
|
-
```ts
|
|
289
|
-
import {
|
|
290
|
-
capture,
|
|
291
|
-
flushTelemetry,
|
|
292
|
-
measure,
|
|
293
|
-
page,
|
|
294
|
-
setTelemetryUser,
|
|
295
|
-
track,
|
|
296
|
-
} from '@novel-isr/engine/runtime';
|
|
297
|
-
|
|
298
|
-
setTelemetryUser({ id: userId, tenantId });
|
|
299
|
-
track('review.submit', { bookId, score }, { tags: { feature: 'reviews' } });
|
|
300
|
-
measure('search.latency', durationMs, { unit: 'ms', tags: { route: '/search' } });
|
|
301
|
-
capture(error, { source: 'rating-widget', extra: { bookId } });
|
|
302
|
-
page('/custom-router/books/1'); // 常规路由不需要,engine 会自动上报 page_view
|
|
303
|
-
await flushTelemetry();
|
|
304
|
-
```
|
|
305
|
-
|
|
306
|
-
这些调用复用 `runtime.telemetry.events/errors` 的同一套队列、采样、重试和 sendBeacon,不需要业务关心 transport。
|
|
307
|
-
API 语义:
|
|
308
|
-
|
|
309
|
-
- `track`:业务事件,例如收藏、评分、搜索提交。
|
|
310
|
-
- `capture`:已知业务失败或组件错误边界,补充 `source/tags/extra/fingerprint`。
|
|
311
|
-
- `measure`:一次原始数值样本,例如请求耗时、队列等待时间、交互延迟。
|
|
312
|
-
- `page`:自定义 router 的页面浏览;普通 `pushState/popstate` 由 engine 自动处理。
|
|
313
|
-
- `setTelemetryUser`:设置后续上报的 user / tenant / segment 上下文。
|
|
314
|
-
- `flushTelemetry`:登出、支付跳转、关闭前主动 flush。
|
|
315
|
-
|
|
316
|
-
`measure()` 只发送一次原始观测值;p95、趋势、慢页面排行和告警阈值应该在后端 /
|
|
317
|
-
dashboard 聚合,不在浏览器里做二级统计。
|
|
318
|
-
Web Vitals / INP 也是同一原则:浏览器只发送 `{ name, value }` 这类事实样本,
|
|
319
|
-
服务端按 route、release、device、tenant 和用户分群计算 p75/p95 与评级。
|
|
320
|
-
|
|
321
|
-
`entry.tsx` 的 hooks 仍然保留,适合补充上下文和业务语义:
|
|
322
|
-
|
|
323
|
-
```ts
|
|
324
|
-
// src/entry.tsx
|
|
325
|
-
export default {
|
|
326
|
-
devInspector: true,
|
|
327
|
-
beforeStart({ telemetry }) {
|
|
328
|
-
telemetry.setUser(readPublicUser());
|
|
329
|
-
telemetry.track('app.client_ready', { source: 'entry' });
|
|
330
|
-
},
|
|
331
|
-
onNavigate(url, { telemetry }) {
|
|
332
|
-
telemetry.track('navigation.section_enter', { path: url.pathname });
|
|
333
|
-
},
|
|
334
|
-
onActionError(error, actionId, { telemetry }) {
|
|
335
|
-
// engine 已自动错误上报;这里只补一条产品漏斗事件。
|
|
336
|
-
telemetry.track('server_action.failure_seen', {
|
|
337
|
-
actionId,
|
|
338
|
-
message: error instanceof Error ? error.message : String(error),
|
|
339
|
-
});
|
|
340
|
-
},
|
|
341
|
-
};
|
|
342
|
-
```
|
|
343
|
-
|
|
344
|
-
完整的「getting started」(含 i18n / SEO / Server Actions)请看 **[docs/getting-started.md](./docs/getting-started.md)**。
|
|
345
|
-
|
|
346
|
-
## 核心卖点
|
|
347
|
-
|
|
348
|
-
```
|
|
349
|
-
┌──────────────────────────────────────────────────────┐
|
|
350
|
-
│ 用户写的代码(业务) │
|
|
351
|
-
│ src/routes.tsx ← 唯一路由源 │
|
|
352
|
-
│ src/app.tsx ← App shell + routes 调用 │
|
|
353
|
-
│ src/pages/, components/ ← 业务组件 │
|
|
354
|
-
│ src/actions/ ← Server Actions │
|
|
355
|
-
│ src/entry.server.tsx ← (可选) 请求期 hooks │
|
|
356
|
-
│ ssr.config.ts ← (可选) 路由级渲染模式 │
|
|
357
|
-
└──────────────────────┬───────────────────────────────┘
|
|
358
|
-
│
|
|
359
|
-
┌──────────────────────▼───────────────────────────────┐
|
|
360
|
-
│ Engine(默认提供,零配置) │
|
|
361
|
-
│ • RSC fetch handler(@vitejs/plugin-rsc) │
|
|
362
|
-
│ • SSR HTML 转换(react-dom/server.edge) │
|
|
363
|
-
│ • 浏览器水合 / 客户端导航 / Server Action 调用 │
|
|
364
|
-
│ • ISR 缓存(LRU + SWR + 标签失效) │
|
|
365
|
-
│ • SSG spider(构建期预生成) │
|
|
366
|
-
│ • SEO sitemap / robots / OG image │
|
|
367
|
-
│ • page-level SEO + API SEO 下发 │
|
|
368
|
-
│ • i18n URL 路由 + 字典缓存 + getI18n() │
|
|
369
|
-
│ • A/B testing │
|
|
370
|
-
│ • csr-shell fallback(server 崩溃自救) │
|
|
371
|
-
│ • dev render inspector(开发态渲染模式浮层) │
|
|
372
|
-
│ • browser analytics / error-reporting 生命周期桥接 │
|
|
373
|
-
│ • Sentry / Datadog / OTel adapter(一行接入) │
|
|
374
|
-
│ • Image / Font 优化插件(next-style) │
|
|
375
|
-
└──────────────────────────────────────────────────────┘
|
|
376
|
-
```
|
|
377
|
-
|
|
378
|
-
**真正甩开 Next.js 的优势**:
|
|
379
|
-
- Vite 8 dev HMR(不是 Webpack/Turbopack)
|
|
380
|
-
- 单 Express 进程,可 hack 中间件链
|
|
381
|
-
- SEO 在 page export + runtime.seo 下发层分层收口,不散落到组件渲染树
|
|
382
|
-
- L1+L2 hybrid cache(进程内 LRU + 可选 Redis 写穿)
|
|
383
|
-
- A/B 变体内建
|
|
384
|
-
- 显式 `RenderModeType = 'ssg' | 'isr' | 'ssr'`,不靠隐式 segment config
|
|
385
|
-
|
|
386
|
-
## 性能 benchmark
|
|
387
|
-
|
|
388
|
-
baseline:[`bench/baseline.json`](./bench/baseline.json) —— 由 [`bench/app/`](./bench/app/)
|
|
389
|
-
(self-contained 最小 ISR 应用)跑出。bench 结果会写入 `bench_protocol` 与
|
|
390
|
-
`runner_id`,只有协议、并发档、时长、Node major 和 runner class 一致时才做
|
|
391
|
-
raw QPS/P95 退化比较;否则只做当前结果健康检查并提示重新播种 baseline。
|
|
392
|
-
|
|
393
|
-
当前基线协议:Node 22 · 单进程 · 3s warmup · 8s/tier · 2s cooldown ·
|
|
394
|
-
tiers 10/100/1000。
|
|
395
|
-
|
|
396
|
-
复现:`cd bench/app && pnpm run build && pnpm start`,
|
|
397
|
-
另一终端跑 `BENCH_TIERS=10,100,1000 BENCH_DURATION=8 pnpm bench`。bench 退化
|
|
398
|
-
追踪走 [`.github/workflows/bench.yml`](./.github/workflows/bench.yml)。GitHub hosted
|
|
399
|
-
runner 跨次硬件不一致时必须重新播种同一 runner class 的 baseline,不能把本地
|
|
400
|
-
Mac/PC 结果直接拿去 gate CI。详细:[docs/performance.md](./docs/performance.md)。
|
|
401
|
-
|
|
402
|
-
## 文档
|
|
403
|
-
|
|
404
|
-
按主题查:
|
|
405
|
-
|
|
406
|
-
| 主题 | 文档 |
|
|
407
|
-
|---|---|
|
|
408
|
-
| 从零搭一个站 | [getting-started.md](./docs/getting-started.md) |
|
|
409
|
-
| 渲染模式(ISR / SSR / SSG / csr-shell) | [render-modes.md](./docs/render-modes.md) |
|
|
410
|
-
| 开发态渲染检查器(Novel ISR Inspector) | [dev-inspector.md](./docs/dev-inspector.md) |
|
|
411
|
-
| 缓存与失效(cacheTag / revalidate / Redis 双层) | [caching.md](./docs/caching.md) |
|
|
412
|
-
| SiteHooks 配置(beforeRequest / i18n / SEO / A/B) | [site-hooks.md](./docs/site-hooks.md) |
|
|
413
|
-
| i18n URL 路由 + 语言协商 | [i18n.md](./docs/i18n.md) |
|
|
414
|
-
| 可观测性(Sentry / Datadog / OTel / Prometheus) | [observability.md](./docs/observability.md) |
|
|
415
|
-
| 生产部署(环境变量 / Docker / Edge runtime / Middleware) | [deployment.md](./docs/deployment.md) |
|
|
416
|
-
| 验证 RSC 是否真的隐藏 server 代码 | [rsc-testing.md](./docs/rsc-testing.md) |
|
|
417
|
-
| 排错与常见坑 | [troubleshooting.md](./docs/troubleshooting.md) |
|
|
418
|
-
| SSR/SPA 失效降级链路 | [deployment/ssr-spa-failover.md](./docs/deployment/ssr-spa-failover.md) |
|
|
419
|
-
|
|
420
|
-
## 渲染模式(一句话)
|
|
421
|
-
|
|
422
|
-
| 模式 | 行为 | 用户级可选 |
|
|
423
|
-
|---|---|---|
|
|
424
|
-
| **isr** | 显式 TTL,过期 SWR 回放 + 后台重渲。命中即入缓存。 | ✅ |
|
|
425
|
-
| **ssr** | 永不入缓存,每次跑完整 RSC + SSR 管线。 | ✅ |
|
|
426
|
-
| **ssg** | 构建期 spider 预生成磁盘 HTML,运行期 TTL × 24。 | ✅ |
|
|
427
|
-
| `csr-shell` | server 崩溃时返回壳 HTML,浏览器自救拉 `_.rsc`。 | ❌(自动兜底) |
|
|
428
|
-
|
|
429
|
-
```
|
|
430
|
-
FallbackChain(自动降级):
|
|
431
|
-
isr → cached → regenerate → server → csr-shell
|
|
432
|
-
ssg → static → regenerate → server → csr-shell
|
|
433
|
-
ssr → server → csr-shell
|
|
434
|
-
```
|
|
435
|
-
|
|
436
|
-
详情:[docs/render-modes.md](./docs/render-modes.md)。
|
|
437
|
-
|
|
438
|
-
## 开发态渲染检查器
|
|
439
|
-
|
|
440
|
-
`pnpm dev` 时,engine 默认 client runtime 会自动注入右下角 **Novel ISR Inspector**。
|
|
441
|
-
它属于 engine,不属于业务 UI:
|
|
442
|
-
|
|
443
|
-
- 通过响应头读取 `x-resolved-mode`、`x-render-strategy`、`x-cache-status`、`x-fallback-used`、`content-language`、`x-i18n-source`
|
|
444
|
-
- 可以在当前 URL 上切换 `?mode=isr|ssr|ssg`,或强制 `?__csr-shell=1` 验证 CSR fallback
|
|
445
|
-
- Shadow DOM 隔离样式,不污染业务 CSS
|
|
446
|
-
- 仅 dev 显示,生产不显示
|
|
447
|
-
|
|
448
|
-
如果业务要关闭它,放到 **client entry**:
|
|
449
|
-
|
|
450
|
-
```ts
|
|
451
|
-
// src/entry.tsx
|
|
452
|
-
export default {
|
|
453
|
-
devInspector: false,
|
|
454
|
-
};
|
|
455
|
-
```
|
|
456
|
-
|
|
457
|
-
不要放到 `src/entry.server.tsx`。`entry.server.tsx` 是 server hooks,不能把 server-only
|
|
458
|
-
配置直接透给浏览器;需要跨端公共配置时应该走 `ssr.config.ts` 或 engine 注入的 client-safe
|
|
459
|
-
public config。详见 [docs/dev-inspector.md](./docs/dev-inspector.md)。
|
|
460
|
-
|
|
461
|
-
## Routes / SEO / i18n 标准写法
|
|
462
|
-
|
|
463
|
-
### Routes:业务只写一个源
|
|
464
|
-
|
|
465
|
-
`defineRoutes({ routes, notFound })` 是业务唯一需要维护的路由声明。不要在业务项目里再拆 `routes.ssr`、`routes.spa`、`spaModules`、`ssrModules` 或手写 loader 分支。第一性原理很简单:一条路由只应该对应一棵 RSC tree,ISR / SSR / SSG / CSR recovery 的执行策略是 engine 的职责。
|
|
466
|
-
|
|
467
|
-
```tsx
|
|
468
|
-
import { defineRoutes } from '@novel-isr/engine/runtime';
|
|
469
|
-
|
|
470
|
-
export const { routes } = defineRoutes({
|
|
471
|
-
notFound: { load: () => import('./pages/NotFoundPage') },
|
|
472
|
-
routes: [{ path: '/', load: () => import('./pages/HomePage') }],
|
|
473
|
-
});
|
|
474
|
-
```
|
|
475
|
-
|
|
476
|
-
### Page SEO:页面声明默认值,API 可覆盖
|
|
477
|
-
|
|
478
|
-
页面模块可以导出静态 `seo` 或动态 `seo(ctx)` / `generateSeo(ctx)`。Engine 会在 server entry 里先加载 i18n,再解析 page SEO,因此页面 SEO 里可以直接调用 `getI18n()`。
|
|
479
|
-
|
|
480
|
-
```tsx
|
|
481
|
-
// src/pages/BookDetailPage.tsx
|
|
482
|
-
import { getI18n } from '@novel-isr/engine/runtime';
|
|
483
|
-
|
|
484
|
-
export async function seo({ params }: { params: { id: string } }) {
|
|
485
|
-
const book = await fetchBook(params.id);
|
|
486
|
-
return {
|
|
487
|
-
title: getI18n('seo.book.title', { title: book.title }),
|
|
488
|
-
description: book.summary,
|
|
489
|
-
ogType: 'book',
|
|
490
|
-
image: book.cover,
|
|
491
|
-
};
|
|
492
|
-
}
|
|
493
|
-
|
|
494
|
-
export default async function BookDetailPage() {
|
|
495
|
-
// ...
|
|
496
|
-
}
|
|
497
|
-
```
|
|
498
|
-
|
|
499
|
-
`runtime.seo` 用来接 API / CMS 下发的 SEO:`endpoint`、`ttl`、`fallbackLocal`
|
|
500
|
-
都放在 `ssr.config.ts`。`entry.server.tsx` 不承载 SEO 数据源配置,只负责本次请求的
|
|
501
|
-
用户、租户、分层和错误上报。
|
|
502
|
-
|
|
503
|
-
合并顺序:`page seo` 提供页面默认值,`SiteHooks seo` 提供远端覆盖值;最终 `<title>`、`meta`、canonical、Open Graph、JSON-LD 都由 engine 注入到 SSR HTML 的 `<head>`,业务组件里不需要手写 `<title>` / `<meta>`。
|
|
504
|
-
|
|
505
|
-
### i18n:服务端拉取一次,RSC payload 复用
|
|
506
|
-
|
|
507
|
-
商业项目推荐由 API 下发字典。`runtime.i18n` 统一声明 `locales`、`defaultLocale`、
|
|
508
|
-
`endpoint`、`ttl`、`fallbackLocal`;engine 会生成请求期 loader,页面不需要写 Provider。
|
|
509
|
-
|
|
510
|
-
业务侧统一用 `getI18n(key, params?, fallback?)`,不需要手写 Provider。
|
|
511
|
-
|
|
512
|
-
```tsx
|
|
513
|
-
import { getI18n } from '@novel-isr/engine/runtime';
|
|
514
|
-
|
|
515
|
-
getI18n('home.hero.title');
|
|
516
|
-
getI18n('book.count', { count: 12 }); // 字典里写 "共 {count} 本书"
|
|
517
|
-
```
|
|
518
|
-
|
|
519
|
-
变量占位符是 `{name}`,不是 `$name`。例如:
|
|
93
|
+
`package.json` 脚本:
|
|
520
94
|
|
|
521
95
|
```json
|
|
522
96
|
{
|
|
523
|
-
"
|
|
524
|
-
"
|
|
525
|
-
"
|
|
97
|
+
"scripts": {
|
|
98
|
+
"dev": "isr-engine dev",
|
|
99
|
+
"build": "vite build",
|
|
100
|
+
"start": "isr-engine start"
|
|
526
101
|
}
|
|
527
102
|
}
|
|
528
103
|
```
|
|
529
104
|
|
|
530
|
-
|
|
531
|
-
|
|
532
|
-
|
|
533
|
-
|
|
534
|
-
|
|
105
|
+
```bash
|
|
106
|
+
npm run dev # 默认 http://localhost:3000
|
|
107
|
+
npm run build # 构建 RSC/SSR/client,并预渲染 SSG 路由
|
|
108
|
+
NODE_ENV=production npm run start # 从应用根目录启动生产服务
|
|
109
|
+
```
|
|
535
110
|
|
|
536
|
-
|
|
537
|
-
- **Rate limit** 在 CDN / WAF / API Gateway 层做:Cloudflare WAF / AWS WAF / Vercel Edge / Kong / Envoy
|
|
538
|
-
- **Trace + 错误** 走 OpenTelemetry → Honeycomb / Datadog / Sentry
|
|
539
|
-
- **业务事件埋点** 仍在 `runtime.telemetry.events`(engine 提供,跟 client 自动接入)
|
|
111
|
+
`dev`、`start` 接受 `--port <port>` 和 `--host <host>`,显式参数覆盖配置。`dev --no-open` 关闭自动打开浏览器。构建和启动生产进程时通过运行环境设置 `NODE_ENV`,避免 `.env*` 中的 `NODE_ENV=development` 影响生产构建。
|
|
540
112
|
|
|
541
|
-
|
|
113
|
+
## 渲染与生产缓存
|
|
542
114
|
|
|
543
|
-
|
|
115
|
+
| 模式 | 行为 |
|
|
116
|
+
| --- | --- |
|
|
117
|
+
| `isr` | 按 TTL 缓存;SWR 窗口内返回旧响应并后台重渲,窗口结束后重新生成。 |
|
|
118
|
+
| `ssg` | 构建时预生成配置的路由;运行时仍受缓存新鲜度与失效策略管理。 |
|
|
119
|
+
| `ssr` | 每次请求渲染,跳过共享页面缓存。 |
|
|
544
120
|
|
|
545
|
-
`
|
|
121
|
+
TTL 与 SWR 单位为秒。`routes` 控制渲染策略;页面路由可使用 `isr-engine/runtime` 的 `defineRoutes` 统一声明。渲染异常的 `csr-shell` 是自动恢复策略;origin 进程不可用时的切换需在反向代理/CDN 配置。
|
|
546
122
|
|
|
547
|
-
|
|
548
|
-
|
|
549
|
-
|
|
550
|
-
|
|
551
|
-
|
|
552
|
-
ops: {
|
|
553
|
-
authToken: process.env.ISR_OPS_TOKEN,
|
|
554
|
-
tokenHeader: 'x-isr-admin-token',
|
|
555
|
-
health: { enabled: true, public: true },
|
|
556
|
-
metrics: { enabled: process.env.ENABLE_METRICS === '1', public: false },
|
|
557
|
-
},
|
|
558
|
-
}
|
|
559
|
-
```
|
|
123
|
+
- 未配置 `runtime.redis.url/host` 时使用进程内存缓存,重启即清空,各实例独立。
|
|
124
|
+
- 显式配置 Redis 后启用远端版本校验和跨实例失效广播,需保留可选依赖 `ioredis`;Redis 连接只读取配置,须如示例显式接入环境变量。多实例共享相同应用的前缀与频道,不同应用/环境使用独立命名空间。
|
|
125
|
+
- 登录态、权限相关或个性化页面应配置为 `ssr`,并在业务层验证身份。请求 hooks 与缓存标签不提供访问控制,也不会自动按用户隔离页面。
|
|
126
|
+
- 授权头、普通业务 Cookie,以及 `private`/`no-store` 等响应会触发缓存保护;不要依赖这些保护代替路由策略。`anon` 与实验 Cookie 有专门的共享缓存规则。
|
|
127
|
+
- Server Component 使用 `cacheTag('site-content')` 声明依赖;数据更新成功后,在受业务鉴权保护的服务端代码中 `await revalidateTag('site-content')` 或 `await revalidatePath('/about')`,从 `isr-engine/rsc` 导入。
|
|
560
128
|
|
|
561
|
-
- `
|
|
562
|
-
- `false`:端口被占用时最多尝试后续 20 个端口,适合本地开发。
|
|
563
|
-
- `server.strictPort` 是公开配置的一部分;生产项目应显式写出,方便审查部署行为。
|
|
564
|
-
|
|
565
|
-
## 与业界方案对比
|
|
566
|
-
|
|
567
|
-
| 能力 | Next.js App Router | Waku | RedwoodJS | **isr-engine** |
|
|
568
|
-
|---|---|---|---|---|
|
|
569
|
-
| RSC 双 entry 模型 | ✅ 自实现 | ✅ plugin-rsc | ✅ 自实现 | ✅ plugin-rsc |
|
|
570
|
-
| ISR 缓存层 | ✅ | ❌ | ⚠️ | ✅ |
|
|
571
|
-
| `revalidatePath` / `revalidateTag` | ✅ | ⚠️ 实验 | ❌ | ✅ |
|
|
572
|
-
| `cacheTag` 精准失效 | ✅ | ❌ | ❌ | ✅ |
|
|
573
|
-
| 路由级 mode 配置 | ⚠️ segment config | ❌ | ❌ | ✅ ssr.config.ts |
|
|
574
|
-
| zero-config 入口 | ⚠️ 必须用 app/ 文件夹 | ✅ | ⚠️ | ✅ routes + app.tsx |
|
|
575
|
-
| csr-shell server 崩溃兜底 | ❌ | ❌ | ❌ | ✅ |
|
|
576
|
-
| 构建栈灵活度 | ❌ 绑死自家栈 | ✅ Vite | ❌ 绑死自家栈 | ✅ Vite |
|
|
577
|
-
| 内置图片 / 字体优化 | ✅ | ❌ | ⚠️ | ✅ |
|
|
578
|
-
| Edge runtime 支持 | ✅ | ⚠️ | ❌ | ✅(CF / Vercel adapter;Deno / Bun 走原生 `{fetch}`) |
|
|
579
|
-
| 单元测试覆盖 | 数千用例 | ⚠️ | ✅ | 60 文件 / 728 tests / ~61% |
|
|
580
|
-
|
|
581
|
-
定位:**中等规模业务的 ISR / SSG / Fallback 编排层**,构建于 React 19 + `@vitejs/plugin-rsc` 官方流水线之上。
|
|
582
|
-
|
|
583
|
-
## 生产可用性诚实评估
|
|
584
|
-
|
|
585
|
-
**当前阶段:alpha** —— 单一首发项目(novel-rating)在自用,外部用户尚未 burn-in。
|
|
586
|
-
v2.1 做了 Security & Reliability 硬化,v2.2 加了 ISR 缓存层 single-flight /
|
|
587
|
-
OOM 防御 / 命名空间失效 / 边缘预热 / CPU-aware 并发 5 项工业级优化,
|
|
588
|
-
v2.3.1 收口了消费侧首跑 0 配置 + express 5 + 入口架构清理,
|
|
589
|
-
v2.5 系列补上 ISR 缓存可观测性(`X-Cache-Stale-Reason` / inventory 端点)、500 兜底页
|
|
590
|
-
和 telemetry 上传退避。但**离 1.0 stable 还差**:
|
|
591
|
-
|
|
592
|
-
✅ **稳的部分**:
|
|
593
|
-
- Flight 协议委托给官方 `@vitejs/plugin-rsc@^0.5.26`,不自维护
|
|
594
|
-
- 依赖全是工业级(Express 5 / Helmet / Prometheus / sitemap / lru-cache / ioredis)
|
|
595
|
-
- 728 tests / ~61% 行覆盖;CI 任何分支 push 都跑 lint+typecheck+test
|
|
596
|
-
- bench 退化追踪走 nightly `bench.yml`(信息性输出,不 gate release)
|
|
597
|
-
- GitHub Packages 发布有 3 段 gate(lint+test+build),任一失败 → 不发布
|
|
598
|
-
- 安全硬化覆盖了 Set-Cookie 跨用户回放、SSG 路径穿越、Redis Buffer 破损、
|
|
599
|
-
Pub/Sub 消息丢失等 10 项审计发现项
|
|
600
|
-
- 消费侧首跑 0 配置:v2.3.1 后 `vite.config.ts` 三件套真的能跑起来(详见 CHANGELOG)
|
|
601
|
-
|
|
602
|
-
⚠️ **真上生产你必须知道**:
|
|
603
|
-
- **只有首发项目在用**,未在第二个独立项目里完整 burn-in 过;社区 review 才刚开始
|
|
604
|
-
- 浏览器侧没有持续跑的 e2e(728 测试主要是 Node 侧单测),靠人工
|
|
605
|
-
smoke test。任何 React 19 / plugin-rsc / Vite 升级都需要先在 bench app 里手验
|
|
606
|
-
- Origin 协议只支持 `http1.1` / `https`;HTTP/2 / HTTP/3 应在 CDN / Nginx / Caddy / ALB 终结
|
|
607
|
-
- bench baseline 跨 GitHub hosted runner 硬件不一致(同 SHA 跑两次能飘 ±60% QPS),
|
|
608
|
-
release 不 gate bench;要做 release-blocking bench gate 需自部 self-hosted runner 锁硬件
|
|
609
|
-
- API 在 v1.0 之前可能有破坏性变更,主要风险面:路由 `defineRoutes` 形态、
|
|
610
|
-
`SiteHooks` 配置 schema、ISR cacheTag/revalidate API。会在 CHANGELOG 中
|
|
611
|
-
明确标注 `BREAKING`,但**没有 codemod**。
|
|
612
|
-
|
|
613
|
-
完整改动列表:[CHANGELOG.md](./CHANGELOG.md)。
|
|
614
|
-
|
|
615
|
-
## 开发
|
|
129
|
+
请求期扩展可放在可选的 `src/entry.server.tsx`,默认导出 `defineAdminSiteHooks({ beforeRequest, onError })`(从 `isr-engine/site-hooks` 导入)。部署配置留在 `ssr.config.ts`;Server Component 用 `getRequestContext()` 读取 hooks 注入的上下文。
|
|
616
130
|
|
|
617
|
-
|
|
618
|
-
pnpm install
|
|
619
|
-
pnpm test # vitest run
|
|
620
|
-
pnpm lint # eslint(含 prettier check via eslint-plugin-prettier)
|
|
621
|
-
pnpm type-check # tsc --noEmit
|
|
622
|
-
pnpm bench # autocannon load test(不阻塞)
|
|
623
|
-
pnpm check # type-check + lint + test
|
|
624
|
-
pnpm build # vite build → dist/
|
|
625
|
-
```
|
|
131
|
+
`Logger.spin()` 返回 Ora 10 对象。`prefixText`、`suffixText` 可为字符串或生成函数;`color` 接受颜色名、`false` 或 `undefined`;自定义 spinner 的 `interval` 必须是正安全整数。
|
|
626
132
|
|
|
627
|
-
|
|
133
|
+
`Logger.getInstance({ logFile })` 的文件输出为 JSON Lines,每行独立保存时间、级别、请求上下文、参数与错误;采集程序应按 JSON 解析,原有纯文本文件可在升级前轮转。
|
|
628
134
|
|
|
629
|
-
|
|
630
|
-
npm Enterprise / GitHub Packages)。**任何项目**都可以作为消费方接它,通过语义
|
|
631
|
-
化版本号引用,**不**用 `file:../isr-engine` 这种 sibling 相对路径——sibling 假设
|
|
632
|
-
让两个 repo 互相强耦合,CI checkout 也跑不通。
|
|
135
|
+
## 运维与部署
|
|
633
136
|
|
|
634
|
-
|
|
137
|
+
部署保留完整 `dist/`、应用依赖及 `ssr.config.*`;配置编译需要应用根目录可写的 `.isr-cache/`。容器按需设置 `HOST=0.0.0.0`,反向代理后显式配置 `server.trustProxy` 的可信来源。
|
|
635
138
|
|
|
636
|
-
|
|
637
|
-
# 1. 配 .npmrc(一次性)
|
|
638
|
-
@novel-isr:registry=https://npm.your-company.com/
|
|
639
|
-
//npm.your-company.com/:_authToken=${NPM_TOKEN}
|
|
640
|
-
|
|
641
|
-
# 2. package.json 里写语义版本号
|
|
642
|
-
{ "dependencies": { "@novel-isr/engine": "^2.6.2" } }
|
|
139
|
+
`/health` 默认公开。生产 `/metrics` 默认关闭;非公开 metrics/inventory 未配置 `server.ops.authToken` 会自动关闭。启用后通过 `Authorization: Bearer <token>` 或配置的 token header 访问;设为 `public: true` 会绕过 token 校验。
|
|
643
140
|
|
|
644
|
-
|
|
645
|
-
pnpm install
|
|
646
|
-
```
|
|
141
|
+
引擎运维接口、静态 HTML 文件读取和 SEO 路由分别使用进程内请求预算;超额返回 `429` 与 `Retry-After`。通过 `server.requestLimits.{ops,staticHtml,seo}` 配置 `windowMs`、单客户端 `maxRequests`、总量 `globalMaxRequests` 与容量 `maxClients`,均须为正整数。默认每分钟单客户端/总量分别为 `120/1200`、`600/12000`、`120/1200`;缓存 HIT 与应用 SSR/API 不计入这些预算。
|
|
647
142
|
|
|
648
|
-
|
|
143
|
+
Google 字体自托管只接受指定 Google HTTPS 来源,验证下载内容后交给 Vite 输出;`outDir` 相对构建输出目录,开发环境从内存提供资源。下载失败会使该优化任务失败,构建不再改写应用 `public/`。
|
|
649
144
|
|
|
650
145
|
```bash
|
|
651
|
-
|
|
652
|
-
|
|
653
|
-
|
|
654
|
-
# 任何消费项目端
|
|
655
|
-
cd <YOUR_CONSUMER_PROJECT> && pnpm link --global @novel-isr/engine
|
|
656
|
-
# 改完取消 link
|
|
657
|
-
pnpm unlink --global @novel-isr/engine && pnpm install
|
|
146
|
+
curl -fsS http://localhost:3000/health
|
|
147
|
+
curl -fsS -H "x-isr-admin-token: $ISR_OPS_TOKEN" \
|
|
148
|
+
http://localhost:3000/__isr/cache/inventory
|
|
658
149
|
```
|
|
659
150
|
|
|
660
|
-
|
|
661
|
-
|
|
662
|
-
仓库里 3 个 workflow 各司其职:
|
|
663
|
-
|
|
664
|
-
| Workflow | 触发 | 跑什么 | 失败后果 |
|
|
665
|
-
|---|---|---|---|
|
|
666
|
-
| **`ci.yml`** | 任何分支 push + PR 到 main/develop | type-check / lint / test / build | branch 标红,PR 不可 merge |
|
|
667
|
-
| **`bench.yml`** | nightly 02:00 UTC + 手动 + perf-sensitive 路径 PR | 起 bench app + 跑 bench + 对比 `bench/baseline.json` | 信息性 fail(不阻断 release,只用于追踪退化) |
|
|
668
|
-
| **`release.yml`** | `git push v*.*.*` tag | 3 段 gate(type+lint / test / build)→ `pnpm publish --access restricted` 到 GitHub Packages | 任一段失败 → 不发布 |
|
|
669
|
-
|
|
670
|
-
**发布到 GitHub Packages**:
|
|
151
|
+
排查页面时先看 `X-Cache-Status`、`X-Resolved-Mode`、`X-Render-Strategy`。本地代理验证可用 `isr-engine test-fallback-local --help`;生产切换由部署层完成,浏览器恢复仍依赖可用的资源与数据服务。
|
|
671
152
|
|
|
672
|
-
|
|
673
|
-
2. 本地:
|
|
674
|
-
```bash
|
|
675
|
-
# 改 package.json version 到 X.Y.Z
|
|
676
|
-
git tag vX.Y.Z
|
|
677
|
-
git push --tags
|
|
678
|
-
```
|
|
679
|
-
3. GitHub Actions 自动跑 release.yml;任一 gate 失败 → 不发布。
|
|
153
|
+
## 公共入口
|
|
680
154
|
|
|
681
|
-
|
|
155
|
+
| 导入路径 | 用途 |
|
|
156
|
+
| --- | --- |
|
|
157
|
+
| `isr-engine` | Vite 插件、Node 编排 API 与公共类型。 |
|
|
158
|
+
| `isr-engine/config` | `defineIsrConfig`、`defineRuntimeConfig`。 |
|
|
159
|
+
| `isr-engine/rsc` | 缓存标签、失效、服务端请求上下文。 |
|
|
160
|
+
| `isr-engine/runtime` | 页面路由、边界、i18n 与浏览器 telemetry。 |
|
|
161
|
+
| `isr-engine/site-hooks` | 请求 hooks 工厂与 Cookie 工具。 |
|
|
162
|
+
| `isr-engine/server-entry`、`isr-engine/client-entry` | 高级入口工厂;由 Vite 转译其源码。 |
|
|
163
|
+
| `isr-engine/image` | 图片组件。 |
|
|
164
|
+
| `isr-engine/auto-observability`、`isr-engine/adapters/observability` | 自动观测与观测适配器。 |
|
|
165
|
+
| `isr-engine/adapters/runtime` | Fetch handler 的平台适配器。 |
|
|
166
|
+
| `isr-engine/package.json` | 包元数据。 |
|
|
682
167
|
|
|
683
|
-
|
|
168
|
+
## 文档与发布
|
|
684
169
|
|
|
685
|
-
|
|
170
|
+
配置字段与默认行为见 [公共配置类型](./src/types/ISRConfig.ts) 和 [默认配置](./src/config/defaults.ts)。
|
|
686
171
|
|
|
687
|
-
|
|
688
|
-
2. **第一性原理** —— 不造假概念(csr 不是用户级 mode,是 fallback 兜底)
|
|
689
|
-
3. **横切能力 engine 默认提供** —— trace-id / render-ms / SEO / 安全头自动
|
|
690
|
-
4. **业务扩展用 FaaS hooks** —— 不强制学协议代码
|
|
691
|
-
5. **不手写 Flight** —— 完全依赖 [@vitejs/plugin-rsc](https://github.com/vitejs/vite-plugin-react/tree/main/packages/plugin-rsc),与 React 19 / Vite 8 升级路径对齐
|
|
172
|
+
`main` 的自动发布流程通过验证后由 semantic-release 计算版本,以 npm OIDC 发布到 `registry.npmjs.org`;配置见 [发布工作流](./.github/workflows/publish.yml) 与 [release.config.mjs](./release.config.mjs)。npm 端需绑定对应仓库和工作流的 Trusted Publisher。
|
|
692
173
|
|
|
693
|
-
|
|
174
|
+
发布必须通过依赖审计和 CodeQL `security-extended` 扫描;任何扫描结果或缺失的扫描证据都会阻止发布,原始审计与 SARIF 结果保留为工作流产物。
|
|
694
175
|
|
|
695
|
-
|
|
176
|
+
许可证声明为 **UNLICENSED**,以 `package.json` 为准。
|