From 36d1781509539edc0f360238a768c4b5aa96cfae Mon Sep 17 00:00:00 2001 From: Gaubee Date: Fri, 13 Feb 2026 20:49:39 +0800 Subject: [PATCH] feat(miniapp): support strict URL launch mode --- .../06-Service-Ref/04-MiniApp/02-Ecosystem.md | 1 + .../01-Runtime-Env/02-Miniapp-Manifest.md | 1 + src/services/ecosystem/schema.ts | 1 + src/services/ecosystem/types.ts | 6 ++++ .../__tests__/launch-context.test.ts | 29 +++++++++++++++++-- .../miniapp-runtime/launch-context.ts | 10 +++++-- 6 files changed, 44 insertions(+), 4 deletions(-) diff --git a/docs/white-book/06-Service-Ref/04-MiniApp/02-Ecosystem.md b/docs/white-book/06-Service-Ref/04-MiniApp/02-Ecosystem.md index bd111e002..d26160e4c 100644 --- a/docs/white-book/06-Service-Ref/04-MiniApp/02-Ecosystem.md +++ b/docs/white-book/06-Service-Ref/04-MiniApp/02-Ecosystem.md @@ -43,6 +43,7 @@ interface MiniappManifest { description?: string; icon: string; // 图标 URL url: string; // 入口 URL + strictUrl?: boolean; // 严格 URL 模式（true 时不注入运行时 query） author?: { name: string; email?: string; diff --git a/docs/white-book/11-DApp-Guide/01-Runtime-Env/02-Miniapp-Manifest.md b/docs/white-book/11-DApp-Guide/01-Runtime-Env/02-Miniapp-Manifest.md index dc93fecad..7a369e667 100644 --- a/docs/white-book/11-DApp-Guide/01-Runtime-Env/02-Miniapp-Manifest.md +++ b/docs/white-book/11-DApp-Guide/01-Runtime-Env/02-Miniapp-Manifest.md @@ -35,6 +35,7 @@ Code: `src/ecosystem/types.ts` - `permissions`: 申请的 BioBridge 权限。 - `permissionsPolicy`: 申请的 Web Permissions Policy 指令列表（如 `clipboard-write`, `camera`）。KeyApp 会根据该字段为 miniapp iframe 注入 `allow`，用于跨域权限委派。 - `splash_screen`: 自定义启动闪屏的行为。 +- `strictUrl`: 严格入口 URL 模式（默认 `false`）。当设置为 `true` 时，KeyApp 会保持 `url` 原样启动，不再自动追加运行时修订参数（如 `__rv`）。 > 注意：跨域 miniapp 需要宿主页面的 `Permissions-Policy` 响应头允许委派，否则 `allow` 不生效。 diff --git a/src/services/ecosystem/schema.ts b/src/services/ecosystem/schema.ts index 8bd075ebe..3335a6b78 100644 --- a/src/services/ecosystem/schema.ts +++ b/src/services/ecosystem/schema.ts @@ -29,6 +29,7 @@ export const MiniappManifestSchema = z longDescription: z.string().optional(), icon: z.string(), url: z.string(), + strictUrl: z.boolean().optional(), version: z.string(), author: z.string().optional(), website: z.string().optional(), diff --git a/src/services/ecosystem/types.ts b/src/services/ecosystem/types.ts index d67544396..86bfbcea4 100644 --- a/src/services/ecosystem/types.ts +++ b/src/services/ecosystem/types.ts @@ -148,6 +148,12 @@ export interface MiniappManifest { icon: string; /** 应用入口 URL */ url: string; + /** + * 严格入口 URL 模式（默认 false） + * - true: 保持 url 原样，不注入运行时修订参数 + * - false: 允许宿主注入运行时参数（例如 __rv） + */ + strictUrl?: boolean; /** 版本号 (semver) */ version: string; /** 作者/开发者 */ diff --git a/src/services/miniapp-runtime/__tests__/launch-context.test.ts b/src/services/miniapp-runtime/__tests__/launch-context.test.ts index 20b351b40..66ec41785 100644 --- a/src/services/miniapp-runtime/__tests__/launch-context.test.ts +++ b/src/services/miniapp-runtime/__tests__/launch-context.test.ts @@ -53,12 +53,37 @@ describe('buildMiniappLaunchContextParams', () => { it('falls back to updated timestamp when version is empty', () => { const manifest = createManifest({ version: '', - updated: '2026-02-13T03:00:00Z', + updatedAt: '2026-02-13T03:00:00Z', }); const result = buildMiniappLaunchContextParams(manifest); expect(result).toEqual({ __rv: 'u:2026-02-13T03:00:00Z' }); }); -}); + it('does not inject revision params when strictUrl is enabled', () => { + const manifest = createManifest({ + version: '4.0.0', + strictUrl: true, + }); + + const result = buildMiniappLaunchContextParams(manifest); + + expect(result).toBeUndefined(); + }); + + it('keeps explicit context params when strictUrl is enabled', () => { + const manifest = createManifest({ + version: '4.1.0', + strictUrl: true, + }); + + const result = buildMiniappLaunchContextParams(manifest, { + from: 'bio-bridge', + }); + + expect(result).toEqual({ + from: 'bio-bridge', + }); + }); +}); diff --git a/src/services/miniapp-runtime/launch-context.ts b/src/services/miniapp-runtime/launch-context.ts index 3f49f23cf..36e21f05b 100644 --- a/src/services/miniapp-runtime/launch-context.ts +++ b/src/services/miniapp-runtime/launch-context.ts @@ -8,7 +8,7 @@ function deriveMiniappRuntimeRevision(manifest: MiniappManifest): string | null return `v:${version}`; } - const updated = manifest.updated?.trim(); + const updated = manifest.updatedAt?.trim(); if (updated && updated.length > 0) { return `u:${updated}`; } @@ -21,6 +21,13 @@ export function buildMiniappLaunchContextParams( contextParams?: Record, ): Record | undefined { const nextContextParams = contextParams ? { ...contextParams } : {}; + if (manifest.strictUrl === true) { + if (Object.keys(nextContextParams).length === 0) { + return undefined; + } + return nextContextParams; + } + if (!(MINIAPP_RUNTIME_REVISION_PARAM in nextContextParams)) { const revision = deriveMiniappRuntimeRevision(manifest); if (revision) { @@ -33,4 +40,3 @@ export function buildMiniappLaunchContextParams( } return nextContextParams; } -