更新记录

1.1.5（2026-08-08）

修复 Android 云打包 Kotlin 字符串插值嵌套引号导致编译失败 HTML/CSS/JS 静态站、files.html、MIME 扩展 static/www 同步 pdf/mp4；Range 支持 集成 NanoHTTPD / GCDWebServer 初版发布

平台兼容性

uni-app x(4.0)

x-httpserver

在 uni-app x App 内开启本地 HTTP 静态服务器，支持 Android / iOS。

功能对齐插件市场 Wind-Http（id=2421）：init / start / finish，用于本地 m3u8、静态 HTML 等场景。

按官方 UTS 插件规范 使用 uni_modules + interface.uts + 分平台实现。

底层库（高星，非手写协议栈）

封装类：LocalHttpServer.kt / LocalHttpServer.swift。完整说明见 THIRD_PARTY.md。

功能

• 指定端口与静态根目录
• 启动 / 停止 / 查询状态
• 静态站点：HTML / CSS / JS 子目录与相对路径（如 ./css/app.css、./js/app.js）
• 静态文件 GET/HEAD，目录默认 index.html
• m3u8 / ts / 图片 / 字体 / wasm 等 MIME
• CORS（默认开启）
• 路径穿越防护
• 兼容 Wind-Http 命名：init / start / finish

工程静态目录约定

static/www/
  index.html          # 入口（link/script 引用 css、js）
  demo-page.html      # 子页面
  css/app.css
  js/app.js
  sample.pdf / sample.mp4 / sample.m3u8

start 时从 App 包同步到服务 path；访问 http://IP:port/ 即可加载完整页面（含 CSS/JS）。

安装

将本目录 x-httpserver 放到项目 uni_modules/ 下。
首次使用原生能力需 制作自定义调试基座 后再运行。

PDF 怎么打开（推荐 uni.openDocument）

web-view / 系统浏览器访问 http://…/sample.pdf 在 Android 上经常打不开。
uni-app x 应用内应使用官方 API：

// 1）已知本地磁盘路径（推荐：服务 rootPath + 文件名）
uni.openDocument({
  filePath: '/data/user/0/.../files/www/sample.pdf',
  fileType: 'pdf',
  success: () => {},
  fail: (e) => { console.log(e) }
})

// 2）只有 HTTP 地址：先下载再打开
uni.downloadFile({
  url: 'http://127.0.0.1:8686/sample.pdf',
  success: (res) => {
    if (res.statusCode == 200) {
      uni.openDocument({
        filePath: res.tempFilePath,
        fileType: 'pdf'
      })
    }
  }
})
// 注意：uni-app x 的 openDocument 无 showMenu 参数（该参数仅部分小程序支持）

Demo 已封装：common/open-pdf.uts 的 openPdfSmart，页面上点 「系统打开 PDF」 即可。

兼容性：Android / iOS 需 HBuilderX 4.71+（见 openDocument 文档）。

常见问题：Not Found: /index.html

原因：服务器已启动，但 静态根目录里没有文件。

• 工程里的 static/www/index.html 不会自动变成 App 内 path 下的磁盘文件
• path: '_doc/www' 实际映射到应用私有目录（init/start 返回的 path 字段是绝对路径）
• 浏览器访问 / 时插件会找 {root}/index.html，目录为空就会 404

处理：

1. 重新 start（1.1.2+）：若根目录没有 index.html，会自动写入默认演示页
2. 或把你的 index.html / m3u8 拷贝/写入到 init 返回的 path 绝对路径下
3. 用手机浏览器打开 localUrl（真机建议用局域网 IP，确认与 status 一致）

API

initHttpServer / init

import { initHttpServer, HttpServerInitOptions } from '@/uni_modules/x-httpserver'

const options = {
  port: 8686,
  path: '_doc/www', // 或绝对路径 / _doc / _documents / _downloads
  allowCors: true,
  success: (res) => {
    console.log(res.localUrl, res.path)
  },
  fail: (err) => {
    console.log(err.errCode, err.errMsg)
  }
} as HttpServerInitOptions

initHttpServer(options)

startHttpServer / start

import { startHttpServer } from '@/uni_modules/x-httpserver'

startHttpServer({
  success: (res) => {
    console.log('running at', res.localUrl)
  }
})

finishHttpServer / finish

import { finishHttpServer } from '@/uni_modules/x-httpserver'

finishHttpServer({
  success: (res) => {
    console.log('stopped', res.running)
  }
})

getHttpServerStatus / 同步辅助

import {
  getHttpServerStatus,
  getHttpServerLocalUrlSync,
  isHttpServerRunningSync
} from '@/uni_modules/x-httpserver'

getHttpServerStatus({
  success: (res) => {
    console.log(res.running, res.port, res.localUrl)
  }
})

console.log(isHttpServerRunningSync())
console.log(getHttpServerLocalUrlSync())

参数说明（兼容 Wind-Http）

错误码

调试建议

1. HBuilderX 配置 Android/iOS 原生运行环境
2. 运行 → 制作自定义调试基座（勾选本 UTS 插件）
3. 使用自定义基座运行，查看控制台 log
4. 将资源写入 path 对应目录后，用系统浏览器或 web-view 访问 localUrl

Android 实现见 utssdk/app-android/LocalHttpServer.kt（NanoHTTPD 薄封装）。
iOS 实现见 utssdk/app-ios/LocalHttpServer.swift（GCDWebServer 薄封装）。

与 AI 编码规则

本仓库根目录已集成 uni-app-x-ai-rules（AGENTS.md、.cursor、.claude 等），用 AI 修改本插件时请遵守 UTS 强类型与 uvue/ucss 约束。