更新记录

1.0.0（2026-07-26）

• 首次发布，支持 uni-app / uni-app x 的 Android 与 iOS App。
• 支持本地 HTTP 服务的创建、启动、停止、重启、销毁和状态查询。
• 支持动态路由、路径参数、查询参数、JSON / 文本请求与响应、自定义状态码和响应头。
• 支持静态目录挂载、目录索引、MIME 推断、可选目录列举和 Cache-Control。
• 支持文件响应、Range / HEAD、multipart 文件上传和 urlencoded 表单。
• 支持 CORS、请求超时、连接数、请求体和上传大小限制。
• 默认仅监听本机回环地址，可显式开放到局域网。
• 提供生命周期事件、统一错误码和日志开关。

平台兼容性

uni-app(5.15)

uni-app x(5.15)

本地 HTTP 服务（hans-http-server）

面向 uni-app x App 的本地 HTTP/1.1 UTS 插件：可挂载静态站点、注册动态接口、接收上传，并为本地媒体访问提供 MIME、Range 与 HEAD 基础能力。本文以 uni-app x 的 .uvue / UTS 用法为主。服务默认只监听本机回环，需要时再显式开放到局域网。

它能做什么

• 在 App 内启动 / 停止一个 HTTP 服务，并获取可访问地址与端口。
• 动态路由：GET / POST / PUT / PATCH / DELETE / OPTIONS / HEAD，支持 :param 路径参数。
• 响应类型：JSON、文本、文件流（支持 Range / HEAD）、空响应；可自定义响应头与状态码。
• 静态站点：挂载目录、目录索引、MIME 推断、可选目录列举、Cache-Control、路径越界拦截。
• 媒体访问：Range（206 Partial Content，支持区间与后缀区间）、HEAD 以及 mp4 / HLS 常用 MIME；实际播放效果取决于平台播放器支持。
• 表单与上传：解析 application/x-www-form-urlencoded；将 multipart/form-data 文件写入受控目录并解析普通字段。
• CORS：可配置来源白名单，自动处理预检与实际响应。
• 生命周期事件、统一错误码、可开关的日志。

平台支持

兼容性说明：同一套公开 API 也可用于传统 uni-app Vue2 / Vue3 的 Android 与 iOS App；本文的代码示例统一采用 uni-app x 的 UTS 写法。nvue、Web、小程序和快应用不支持。

平台配置与权限

host: 'lan' 会让同一局域网内的其他设备访问服务。仅在业务确实需要时启用，并由宿主应用负责访问控制和敏感文件隔离。

安装与导入

从 DCloud 插件市场将插件导入 uni-app x 项目。在 .uvue 页面的 <script setup lang="uts"> 中，从插件根目录导入函数和公开类型，不要直接引用 utssdk 内部文件：

import {
  createHttpServer,
  getResourcePath,
  HttpServer,
  HttpRequest,
  HttpServerInfo,
  HttpServerEvent,
} from '@/uni_modules/hans-http-server'

快速开始

以下代码放在 .uvue 页面的 <script setup lang="uts"> 中：

import {
  createHttpServer,
  getResourcePath,
  HttpServer,
  HttpRequest,
  HttpServerInfo,
  HttpServerEvent,
} from '@/uni_modules/hans-http-server'

const server: HttpServer = createHttpServer({
  host: 'loopback',          // 默认仅本机回环；'lan' 显式开放到局域网
  port: 0,                   // 0 = 由系统分配空闲端口
  logEnabled: true,
})

// 挂载静态目录（必须在 start 之前注册）
server.mount('/assets', {
  root: getResourcePath('/static'),
  index: 'index.html',
})

// 动态接口
server.route('GET', '/api/status', (req: HttpRequest, responseId: string): void => {
  server.respond(responseId, {
    statusCode: 200,
    bodyJson: { ok: true, time: Date.now() },
  })
})

server.route('GET', '/api/users/:id', (req: HttpRequest, responseId: string): void => {
  server.respond(responseId, {
    statusCode: 200,
    bodyJson: { id: req.params['id'], query: req.query },
  })
})

server.route('POST', '/api/upload', (req: HttpRequest, responseId: string): void => {
  // multipart 文件已落盘；form 为普通字段；files 为受控路径列表
  server.respond(responseId, {
    statusCode: 200,
    bodyJson: { files: req.files, fields: req.form },
  })
})

server.route('GET', '/api/file', (req: HttpRequest, responseId: string): void => {
  // 命中文件路由后，Range/HEAD 由插件自动处理
  server.respond(responseId, {
    statusCode: 200,
    filePath: getResourcePath('/files/media.bin'),
    contentType: 'application/octet-stream',
  })
})

server.on('started', (event: HttpServerEvent): void => {
  console.log('started', event.info)
})
server.on('error', (event: HttpServerEvent): void => {
  console.error('server error', event.message)
})

async function startServer(): Promise<void> {
  const info: HttpServerInfo = await server.start()
  console.log(info.urls)      // 例如 ['http://127.0.0.1:54321']
}

async function stopServer(): Promise<void> {
  await server.stop()         // 停止后可再次 start
}

async function destroyServer(): Promise<void> {
  await server.destroy()      // 永久释放，不可再 start
}

模块级 API

公开类型

所有公开类型都从插件根目录导入。interface.uts 是 API 类型契约，不要在业务代码中直接引用该文件。

路由回调会跨越 UTS 与原生层，参数和响应必须可序列化。JSON、query、params、headers 与 form 使用 UTSJSONObject；文件内容通过 filePath 返回，不直接在回调中传递二进制对象。

配置项（createHttpServer）

multipart 请求的总大小仍受 maxRequestBodySize 限制。需要接收大文件时，应同时调整请求体上限与单文件上限。

cors 配置：

静态目录配置（StaticMountOptions）

mount() 只能在服务未运行时调用。同一路径下优先查找索引文件；找不到索引时，只有显式开启目录列举才会返回目录内容。

服务实例方法

服务状态按 created -> starting -> running -> stopping -> stopped 变化，destroy() 后进入 destroyed。stop() 后可以再次 start()；destroy() 后不能再次启动。

请求 HttpRequest

响应 HttpRouteResponse（一次性）

原生路由回调的参数必须是可序列化数据，因此处理器收到 responseId，再通过 server.respond(responseId, response) 完成请求。每个请求只能响应一次；超过 requestTimeout 仍未响应时返回 504。

bodyJson、bodyText、filePath 最多设置一个；都不设置时发送空响应。

路由处理器可以在回调返回后再调用 respond()，但必须在 requestTimeout 内完成。超时会返回 504，之后再使用该 responseId 会按“响应已提交或不再等待”处理。

返回对象与事件

start() 返回 HttpServerInfo：

status() 返回 HttpServerStatus：

生命周期监听器收到 HttpServerEvent：

默认值与安全

• 默认仅 loopback：服务默认只监听本机回环地址；开放到局域网必须显式设置 host: 'lan'。
• 静态路径限定：静态服务将相对路径中的 .. 等片段清洗并二次校验，确保响应文件不会逃逸出挂载根目录，越界请求返回 403。
• 上传落盘受控：multipart 文件由插件写入受控 uploadDir（文件名随机化），客户端无法指定目标目录；超过数量 / 大小限制的请求会被拒绝。
• 上传文件清理：上传文件不会由插件自动删除，业务处理完成后必须由宿主清理。Android 与 iOS 不承诺完全一致的失败残留清理行为，不要依赖失败请求自动清理目录。
• 请求体限额：超过 maxRequestBodySize 的请求返回 413。
• CORS 默认关闭：未配置 cors 时不回写任何跨域头。
• 日志安全：日志默认关闭；开启后仅记录生命周期与错误摘要，不写入 Cookie / Authorization / 请求体。

错误码

错误码跨平台稳定，errSubject 固定为 hans-http-server。

import { HttpServerFail } from '@/uni_modules/hans-http-server'

try {
  const info = await server.start()
  console.log('listening', info.urls)
} catch (error) {
  const fail = error as HttpServerFail
  console.error(fail.errCode, fail.errMsg, fail.detail)
}

HttpServerFail 包含 errCode、errSubject、errMsg 和可空的 detail。HTTP 请求解析或尺寸超限会直接向客户端返回对应 HTTP 状态；下表主要用于调用插件 API 时捕获失败。

版本要求

功能限制

• HTTPS / TLS
• WebSocket / SSE / 流式响应
• HTTP pipelining
• HLS / mp4 的跨平台播放器兼容性保证
• 请求体 chunked transfer encoding
• App 进入后台后的持续运行（保活由宿主应用负责）
• IPv6 监听