Phase 1.F: WebView 加载从 file:// 迁到 ylgame://h5 自定义 scheme

为未来 Cocos 子游戏 H5 build 适配铺路(file:// 下 Cocos XHR/fetch 受
null-origin 限制几乎必踩坑),同时保留大厅 + 子游戏跨页 localStorage
共享语义(用单虚拟 host `h5` 让所有 H5 same-origin)。

变更:
- 新增 AppSchemeHandler(WKURLSchemeHandler 单例 + Range/MIME/异步 IO/
  取消语义;闭包只携 Sendable ObjectIdentifier,不捕获 task)
- SandboxPaths 加 lobbyIndexAppURL / subGameIndexAppURL builders
- BridgedWebView 注册 scheme handler(WKWebView init 前)
- WebContainerViewController / SubGameViewController 的 loadFileURL
  → webView.load(URLRequest),OverlayViewController 不变

文档:
- Plan 新增 Phase 1.F (1.18-1.21) + ADR-010 决策记录 + 进度勾选
- Design 新增 §7.6 包含 URL 结构 / 实现要点 / 等价性表 / Cocos 预检脚本
- Contract §0.2 / §4.1 / §10 验收清单同步切换说明(H5 可观察差异:
  location.protocol "file:" → "ylgame:",项目方已 grep 确认现网 H5
  不依赖此字面)

存量影响:file:// → ylgame:// origin 切换时老用户 localStorage 一次性
清零,已与项目方确认业务可接受、不做迁移补偿。

BuildProject 通过。Plan 进度已勾选 1.18/1.19/1.20。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
joywayer
2026-06-29 08:58:00 +08:00
co-authored by Claude Opus 4.7
parent 960adc5491
commit 04e702a99b
8 changed files with 686 additions and 17 deletions
@@ -68,4 +68,30 @@ public enum SandboxPaths {
.appendingPathComponent(start)
.appendingPathComponent("index.html")
}
// MARK: - App scheme URL(Phase 1.F WKURLSchemeHandler 迁移)
//
// 由 AppSchemeHandler 接管的自定义 scheme URL。大厅 + 所有子游戏共用
// 同一虚拟 host (`ylgame://h5`),从而 same-origin → 共享 localStorage。
// 路径前缀区分目标 (`lobby` / `subgame/<dir>`),handler 内反向映射回
// 上面 lobbyRoot / subGameRoot(_:) 的沙盒物理路径。
/// 大厅 H5 入口的 app:// URL:`ylgame://h5/lobby/<gameStart>/index.html`
nonisolated public static var lobbyIndexAppURL: URL {
var c = URLComponents()
c.scheme = AppScheme.scheme
c.host = AppScheme.host
c.path = "/\(AppScheme.lobbyPrefix)/\(BundleConfig.shared.gameStart)/index.html"
// 字面下 path 不含空格 / 中文,force-unwrap 安全
return c.url!
}
/// 子游戏 H5 入口的 app:// URL:`ylgame://h5/subgame/<dir>/<start>/index.html`
nonisolated public static func subGameIndexAppURL(_ dir: String, _ start: String) -> URL {
var c = URLComponents()
c.scheme = AppScheme.scheme
c.host = AppScheme.host
c.path = "/\(AppScheme.subGamePrefix)/\(dir)/\(start)/index.html"
return c.url!
}
}
@@ -0,0 +1,415 @@
//
// AppSchemeHandler.swift
// ylgamehall
//
// WKURLSchemeHandler 实现,承接 `ylgame://h5/...` 自定义 scheme。
// 替代原 loadFileURL 路径,让大厅 + 所有子游戏跑在同一个稳定 origin
// (`ylgame://h5`) 下,从而:
// 1) 共享 localStorage(同 scheme + 同 host = 同 security origin)
// 2) 摆脱 file:// 的 XHR/fetch null-origin 限制(Cocos H5 build 适配前置)
// 3) 给 `<audio>/<video>` 提供 Range 请求支持(Cocos 音频 seek)
//
// 路由:
// ylgame://h5/lobby/<rest...> → SandboxPaths.lobbyRoot/<rest...>
// ylgame://h5/subgame/<dir>/<rest...> → SandboxPaths.subGameRoot(dir)/<rest...>
//
// 设计 / Phase 见 docs/H5-Native-Implementation-Design.md §17(新增)/
// docs/Development-Plan.md Phase 1.F。
//
import Foundation
@preconcurrency import WebKit
import os.log
// MARK: - 常量(项目前缀)
/// 自定义 scheme + host + 路径前缀常量。**所有成员 nonisolated**,让
/// `SandboxPaths`(nonisolated)能在任意上下文拼 URL(项目启用了
/// MainActor-by-default 默认隔离,未标 nonisolated 的 static 会被推断为
/// MainActor 隔离,背景 IO 队列无法访问)。
public enum AppScheme {
/// scheme = "ylgame"(项目前缀,避免与其它 app 自定义 scheme 冲突)
nonisolated public static let scheme = "ylgame"
/// 单虚拟 host = "h5"。**所有 H5 页(大厅 + 所有子游戏)共用此 host**,
/// 确保 same-origin → 共享 localStorage / IndexedDB / sessionStorage。
nonisolated public static let host = "h5"
/// 大厅根路径段:`/lobby/...`
nonisolated public static let lobbyPrefix = "lobby"
/// 子游戏根路径段:`/subgame/<dir>/...`
nonisolated public static let subGamePrefix = "subgame"
}
// MARK: - Handler
/// 自定义 URL scheme 的 WKURLSchemeHandler。**单例**注册到所有 BridgedWebView 的
/// WKWebViewConfiguration(同一实例可挂多个 WKWebViewConfiguration;每个
/// configuration 内每个 scheme 只能注册一次)。
@MainActor
public final class AppSchemeHandler: NSObject, WKURLSchemeHandler {
public static let shared = AppSchemeHandler()
private static let log = Logger(subsystem: "ylgamehall", category: "AppSchemeHandler")
/// 后台 IO 队列。所有 file IO + Range parsing 在此运行,避免阻塞主线程。
private let ioQueue = DispatchQueue(
label: "ylgamehall.app-scheme-handler.io",
qos: .userInitiated,
attributes: .concurrent
)
/// 跟踪进行中的 task。**仅主线程访问**(start / stop / deliver 都在 MainActor)。
/// 用 ObjectIdentifier 作 key 是为了让背景 IO 队列只携带 Sendable 的 key 跨边界,
/// 不把非 Sendable 的 `any WKURLSchemeTask` 捕获进 `@Sendable` 闭包。
/// WKURLSchemeTask 协议规定 stop 后不能再向 task 发任何消息(否则 NSException),
/// 用 `cancelledKeys` 标记取消、`tasksByKey` 持强引用配套使用。
private var tasksByKey: [ObjectIdentifier: any WKURLSchemeTask] = [:]
private var cancelledKeys: Set<ObjectIdentifier> = []
private override init() {
super.init()
}
// MARK: - WKURLSchemeHandler
public func webView(_ webView: WKWebView, start urlSchemeTask: any WKURLSchemeTask) {
let key = ObjectIdentifier(urlSchemeTask)
tasksByKey[key] = urlSchemeTask
guard let url = urlSchemeTask.request.url else {
finish(key: key, withError: AppSchemeError.invalidURL)
return
}
let rangeHeader = urlSchemeTask.request.value(forHTTPHeaderField: "Range")
// 路由 + 文件路径解析(主线程做,廉价)
let resolved: ResolvedRequest
do {
resolved = try Self.resolveRequest(url: url, rangeHeader: rangeHeader)
} catch {
finish(key: key, withError: error)
return
}
// 读盘 + 响应 → 后台队列。注意:闭包只捕获 Sendable 的 `key` / `resolved`,
// 不捕获非 Sendable 的 `urlSchemeTask`,避免数据竞争告警。
ioQueue.async { [weak self] in
let result = Self.readAndBuildResponse(resolved: resolved)
Task { @MainActor in
self?.deliver(result: result, forKey: key)
}
}
}
public func webView(_ webView: WKWebView, stop urlSchemeTask: any WKURLSchemeTask) {
let key = ObjectIdentifier(urlSchemeTask)
// 标记取消,io 队列完成后 deliver 见此标志直接短路。tasksByKey 在 deliver
// / finish 内清理,不在此处提前移除(避免与背景 IO 完成竞态)。
cancelledKeys.insert(key)
}
// MARK: - Routing(nonisolated 纯函数)
fileprivate struct ResolvedRequest {
let fileURL: URL
let url: URL
let rangeHeader: String?
}
/// 把 `ylgame://h5/<prefix>/<rest>` 解析为沙盒实际文件路径。
/// - lobby 前缀:rest 全段拼到 lobbyRoot
/// - subgame 前缀:第一段是 dir,剩余拼到 subGameRoot(dir)
nonisolated fileprivate static func resolveRequest(
url: URL,
rangeHeader: String?
) throws -> ResolvedRequest {
guard url.scheme?.lowercased() == AppScheme.scheme,
url.host?.lowercased() == AppScheme.host
else {
throw AppSchemeError.invalidURL
}
// path 形如 "/lobby/gameStart/index.html" 或 "/subgame/<dir>/<start>/index.html"
let segments = url.path
.split(separator: "/", omittingEmptySubsequences: true)
.map(String.init)
guard let prefix = segments.first else {
throw AppSchemeError.invalidURL
}
let fileURL: URL
switch prefix {
case AppScheme.lobbyPrefix:
let rest = segments.dropFirst().joined(separator: "/")
fileURL = SandboxPaths.lobbyRoot.appendingPathComponent(rest)
case AppScheme.subGamePrefix:
guard segments.count >= 2 else {
throw AppSchemeError.invalidURL
}
let dir = segments[1]
let rest = segments.dropFirst(2).joined(separator: "/")
fileURL = SandboxPaths.subGameRoot(dir).appendingPathComponent(rest)
default:
throw AppSchemeError.invalidURL
}
return ResolvedRequest(fileURL: fileURL, url: url, rangeHeader: rangeHeader)
}
// MARK: - Reading + response building(IO 队列调用)
fileprivate enum BuildResult {
case ok(HTTPURLResponse, Data)
case fail(AppSchemeError)
}
nonisolated fileprivate static func readAndBuildResponse(
resolved: ResolvedRequest
) -> BuildResult {
let fileURL = resolved.fileURL
let fm = FileManager.default
guard fm.fileExists(atPath: fileURL.path),
let attrs = try? fm.attributesOfItem(atPath: fileURL.path),
let size = (attrs[.size] as? NSNumber)?.intValue
else {
return .fail(.fileNotFound(fileURL.path))
}
let mime = MimeMap.mime(forExtension: fileURL.pathExtension)
// Range 请求 → 206
if let rangeHeader = resolved.rangeHeader,
let (start, end) = parseRange(rangeHeader, totalSize: size) {
do {
let handle = try FileHandle(forReadingFrom: fileURL)
defer { try? handle.close() }
try handle.seek(toOffset: UInt64(start))
let length = end - start + 1
let data = try handle.read(upToCount: length) ?? Data()
let response = makePartialResponse(
url: resolved.url,
mime: mime,
start: start,
end: end,
totalSize: size,
contentLength: data.count
)
return .ok(response, data)
} catch {
return .fail(.readFailed(error))
}
}
// 全文件 → 200
do {
let data = try Data(contentsOf: fileURL, options: [.mappedIfSafe])
let response = makeFullResponse(
url: resolved.url,
mime: mime,
contentLength: data.count
)
return .ok(response, data)
} catch {
return .fail(.readFailed(error))
}
}
nonisolated private static func makeFullResponse(
url: URL,
mime: String,
contentLength: Int
) -> HTTPURLResponse {
let headers: [String: String] = [
"Content-Type": mime,
"Content-Length": "\(contentLength)",
// 防御性 CORS:自定义 scheme 同源本不需要 preflight,但部分 Cocos build
// 在 fetch 默认 mode='cors' 下会走 preflight,发回 * 兜底
"Access-Control-Allow-Origin": "*",
// 沙盒文件随升级路径改变(lobby zip 升级直接覆盖原目录),禁强缓存避免错版
"Cache-Control": "no-cache",
"Accept-Ranges": "bytes"
]
return HTTPURLResponse(
url: url,
statusCode: 200,
httpVersion: "HTTP/1.1",
headerFields: headers
)!
}
nonisolated private static func makePartialResponse(
url: URL,
mime: String,
start: Int,
end: Int,
totalSize: Int,
contentLength: Int
) -> HTTPURLResponse {
let headers: [String: String] = [
"Content-Type": mime,
"Content-Length": "\(contentLength)",
"Content-Range": "bytes \(start)-\(end)/\(totalSize)",
"Access-Control-Allow-Origin": "*",
"Cache-Control": "no-cache",
"Accept-Ranges": "bytes"
]
return HTTPURLResponse(
url: url,
statusCode: 206,
httpVersion: "HTTP/1.1",
headerFields: headers
)!
}
/// 解析 Range 头:支持 `bytes=start-end` / `bytes=start-` / `bytes=-suffix`。
/// 不支持 multi-range(逗号分隔),Cocos 不发。
nonisolated private static func parseRange(
_ header: String,
totalSize: Int
) -> (Int, Int)? {
guard header.lowercased().hasPrefix("bytes=") else { return nil }
let spec = String(header.dropFirst("bytes=".count))
if spec.contains(",") { return nil }
let parts = spec.split(separator: "-", maxSplits: 1, omittingEmptySubsequences: false)
guard parts.count == 2 else { return nil }
let startStr = String(parts[0])
let endStr = String(parts[1])
// bytes=-N → 最后 N 字节
if startStr.isEmpty, let suffix = Int(endStr), suffix > 0 {
let start = max(totalSize - suffix, 0)
return (start, totalSize - 1)
}
guard let start = Int(startStr), start >= 0, start < totalSize else { return nil }
if endStr.isEmpty {
return (start, totalSize - 1)
}
guard let end = Int(endStr), end >= start, end < totalSize else { return nil }
return (start, end)
}
// MARK: - Delivery(主线程)
private func deliver(result: BuildResult, forKey key: ObjectIdentifier) {
// task 已被 stop 标记 → 一律不向 task 发任何消息(否则 NSException)。
// 即使如此,仍要从两个表里清理引用避免泄漏。
guard let urlSchemeTask = tasksByKey.removeValue(forKey: key) else { return }
if cancelledKeys.remove(key) != nil { return }
switch result {
case .ok(let response, let data):
urlSchemeTask.didReceive(response)
urlSchemeTask.didReceive(data)
urlSchemeTask.didFinish()
Self.log.debug("→ \(response.statusCode, privacy: .public) \(response.url?.absoluteString ?? "", privacy: .public) \(data.count, privacy: .public)B")
case .fail(let error):
urlSchemeTask.didFailWithError(error.toNSError)
Self.log.error("✗ \(error.debugDescription, privacy: .public)")
}
}
private func finish(key: ObjectIdentifier, withError error: any Error) {
guard let urlSchemeTask = tasksByKey.removeValue(forKey: key) else { return }
if cancelledKeys.remove(key) != nil { return }
let ns = (error as? AppSchemeError)?.toNSError ?? (error as NSError)
urlSchemeTask.didFailWithError(ns)
}
}
// MARK: - Errors
public enum AppSchemeError: Error, CustomDebugStringConvertible, Sendable {
case invalidURL
case fileNotFound(String)
case readFailed(any Error)
public var debugDescription: String {
switch self {
case .invalidURL: return "invalid url"
case .fileNotFound(let p): return "file not found: \(p)"
case .readFailed(let e): return "read failed: \(e)"
}
}
var toNSError: NSError {
switch self {
case .invalidURL:
return NSError(
domain: "AppSchemeHandler",
code: -1,
userInfo: [NSLocalizedDescriptionKey: "invalid url"]
)
case .fileNotFound(let p):
return NSError(
domain: "AppSchemeHandler",
code: 404,
userInfo: [NSLocalizedDescriptionKey: "not found: \(p)"]
)
case .readFailed(let e):
return e as NSError
}
}
}
// MARK: - MIME map
/// 扩展名 → MIME 映射。Cocos H5 build 常用扩展全打表,未命中走
/// `application/octet-stream`(WKWebView 仍能下载,只是不会自动按内容类型行为)。
/// `nonisolated` 让 IO 队列能直接调用(项目 MainActor-by-default)。
enum MimeMap {
nonisolated static func mime(forExtension ext: String) -> String {
let lower = ext.lowercased()
return table[lower] ?? "application/octet-stream"
}
nonisolated private static let table: [String: String] = [
// 文本类
"html": "text/html; charset=utf-8",
"htm": "text/html; charset=utf-8",
"js": "text/javascript; charset=utf-8",
"mjs": "text/javascript; charset=utf-8",
"css": "text/css; charset=utf-8",
"json": "application/json; charset=utf-8",
"txt": "text/plain; charset=utf-8",
"xml": "application/xml; charset=utf-8",
"atlas": "text/plain; charset=utf-8", // Cocos atlas 文件
"fnt": "text/plain; charset=utf-8", // Cocos bitmap font
"plist": "application/x-plist",
"wasm": "application/wasm",
// 图片
"png": "image/png",
"jpg": "image/jpeg",
"jpeg": "image/jpeg",
"gif": "image/gif",
"webp": "image/webp",
"svg": "image/svg+xml",
"ico": "image/x-icon",
"bmp": "image/bmp",
// 音频
"mp3": "audio/mpeg",
"ogg": "audio/ogg",
"oga": "audio/ogg",
"wav": "audio/wav",
"m4a": "audio/mp4",
"aac": "audio/aac",
// 视频
"mp4": "video/mp4",
"m4v": "video/mp4",
"webm": "video/webm",
"mov": "video/quicktime",
// 字体
"ttf": "font/ttf",
"otf": "font/otf",
"woff": "font/woff",
"woff2": "font/woff2",
"eot": "application/vnd.ms-fontobject",
"bin": "application/octet-stream"
]
}
@@ -30,6 +30,18 @@ public final class BridgedWebView: UIView {
configuration.mediaTypesRequiringUserActionForPlayback = []
configuration.processPool = SharedProcessPool.shared
// ── 自定义 URL scheme 注册(Phase 1.F)────────────────────
// 大厅 + 子游戏的 H5 通过 `ylgame://h5/...` 加载,由 AppSchemeHandler 反向
// 映射到沙盒文件。理由(详见 docs/H5-Native-Implementation-Design.md §17):
// - file:// origin 是 null,XHR/fetch 受限;自定义 scheme 是稳定 origin
// - 大厅 + 所有子游戏共用 `ylgame://h5` 单 host → same-origin →
// 共享 localStorage(与现状 file:// 等价)
// - 为未来 Cocos 子游戏 H5 适配铺路
configuration.setURLSchemeHandler(
AppSchemeHandler.shared,
forURLScheme: AppScheme.scheme
)
// ── 在 documentStart 注入 WebViewJavascriptBridge.js ─────
// .atDocumentStart 保证 H5 业务代码运行时 window.WebViewJavascriptBridge 已就绪
if let url = Bundle.main.url(forResource: "WebViewJavascriptBridge",
@@ -245,13 +245,13 @@ public final class SubGameViewController: UIViewController {
try writer.writeBattery(BatteryMonitor.shared.currentLevel)
try writer.writeNetwork(NetworkMonitor.shared.currentCode)
// 3. 加载子游戏 H5(allowingReadAccessTo 给 subGameRoot 才能跨目录引用资源)
// 3. 加载子游戏 H5(Phase 1.F:从 loadFileURL 迁到 AppSchemeHandler)
// URL:ylgame://h5/subgame/<dir>/<start>/index.html
// 与大厅同 host("h5")→ same-origin → 共享 localStorage。
// 跨目录引用自动落回 subGameRoot(<dir>),等价原 allowingReadAccessTo 语义。
splash.update(text: "进入子游戏...", progress: nil)
let indexURL = SandboxPaths.subGameIndex(effectiveGameDir, request.gameStart)
bridgedWebView.webView.loadFileURL(
indexURL,
allowingReadAccessTo: SandboxPaths.subGameRoot(effectiveGameDir)
)
let indexURL = SandboxPaths.subGameIndexAppURL(effectiveGameDir, request.gameStart)
bridgedWebView.webView.load(URLRequest(url: indexURL))
}
/// 子游戏启动期两次 resolve:
@@ -407,12 +407,13 @@ public final class WebContainerViewController: UIViewController {
// 详见 docs/H5-Native-Implementation-Design.md §7.5
try writeAppDataFiles(resolved: resolved)
// 7. 加载本地 H5(allowingReadAccessTo 必须给 lobbyRoot 才能跨目录引用资源)
// 7. 加载本地 H5(Phase 1.F:从 loadFileURL 迁到 AppSchemeHandler)
// URL:ylgame://h5/lobby/<gameStart>/index.html
// AppSchemeHandler 把 /lobby/<rest> 反向映射到 lobbyRoot/<rest> 读盘。
// 跨目录引用(H5 用 ../foo.js)自动落回 lobbyRoot,等价 file:// 的
// allowingReadAccessTo 语义。
splash.update(text: "加载大厅...", progress: nil)
bridgedWebView.webView.loadFileURL(
SandboxPaths.lobbyIndex,
allowingReadAccessTo: SandboxPaths.lobbyRoot
)
bridgedWebView.webView.load(URLRequest(url: SandboxPaths.lobbyIndexAppURL))
}
/// 写 4 个 app_*.js 文件首次值(loadFileURL 之前调一次,monitor 已启动)。