更新记录

1.0.1（2026-04-21） 下载此版本

• 修复 bonjourName 触发 iOS 14+ 本地网络权限检测问题
• 修复 GCDWebServer.init() 非主线程调用导致 SIGABRT 崩溃
• 修复 addGETHandler 对不存在目录触发 GWS_DCHECK 断言崩溃
• 新增 warmupServer 预热接口，减少首次使用延迟
• 新增 setDocumentsPath 接口，支持动态设置 Documents 路径
• 新增 localPathToUrl 路径转换，支持 _doc 前缀自动解析
• 新增端口自动重试机制，端口占用时自动递增尝试
• 新增目录存在性检查，防止无效路径导致崩溃

1.0.0（2026-04-21） 下载此版本

init

平台兼容性

uni-app(5.07)

cy-local-server

基于 GCDWebServer 的 iOS 本地 HTTP 服务器 UTS 插件，用于在 App 内启动本地 HTTP 服务，提供离线瓦片文件访问能力。

平台支持

安装

在 HBuilderX 中通过插件市场导入，或直接将 cy-local-server 目录放入项目的 uni_modules 目录。

API

startServer(options) 启动服务器

启动本地 HTTP 服务器，同步返回服务器信息。

const result = startServer({
  port: 8080,           // 首选端口号，默认 8080
  maxPortRetries: 10,   // 端口重试次数，默认 10
  rootPath: '_doc'      // 服务根目录，默认 _doc
})
// result: { state: 'running', port: 8080, baseUrl: 'http://localhost:8080', rootPath: '_doc' }
// 启动失败返回 null

stopServer() 停止服务器

stopServer()

getServerInfo() 获取服务器信息

const info = getServerInfo()
// info: { state: 'running', port: 8080, baseUrl: 'http://localhost:8080', rootPath: '_doc' }
// 服务器未运行时返回 null

isRunning() 检查是否运行

const running = isRunning() // boolean

localPathToUrl(localPath) 本地路径转 URL

将本地文件路径转换为可通过服务器访问的 URL。

const url = localPathToUrl('_doc/map_cache/xxx/10/123/456.webp')
// url: 'http://localhost:8080/map_cache/xxx/10/123/456.webp'

warmupServer(options?) 预热服务器

提前启动服务器，减少首次使用时的延迟。

warmupServer({
  port: 8080,
  maxPortRetries: 10
})

setDocumentsPath(path) 设置 Documents 路径

设置 iOS Documents 目录的绝对路径，用于 _doc 前缀路径解析。

setDocumentsPath('/var/mobile/.../Documents')

类型定义

type ServerState = 'stopped' | 'starting' | 'running' | 'error'

type ServerOptions = {
  port?: number
  maxPortRetries?: number
  rootPath?: string
}

type ServerInfo = {
  state: ServerState
  port: number
  baseUrl: string
  rootPath: string
}

type WarmupServerOptions = {
  port?: number
  maxPortRetries?: number
}

注意事项

1. 主线程要求：GCDWebServer.init() 内部注册 UIApplication 通知，必须在主线程调用，否则会 SIGABRT 崩溃。插件内部已做主线程检测和自动切换处理。
2. Bonjour 名称：bonjourName 必须为 nil，传非 nil 值会触发 iOS 14+ 本地网络权限检测弹窗。插件内部已处理。
3. 目录存在性：addGETHandler 对不存在的目录会触发 GWS_DCHECK 断言（SIGABRT，无法被 try-catch 捕获），启动前插件会自动检查目录是否存在。
4. 端口重试：当首选端口被占用时，会自动递增端口尝试（最多重试 maxPortRetries 次）。

开发文档

• UTS 语法
• UTS API 插件
• UTS uni-app 兼容模式组件
• UTS 标准模式组件
• Hello UTS