更新记录

1.0.0（2026-07-23） 下载此版本

初始版本

平台兼容性

uni-app(4.31)

uni-app x(4.31)

其他

xyz-httpserver

uni-app x 嵌入式 HTTP 服务器插件，Express 风格 API，支持 Android / iOS / HarmonyOS 三端。

功能特性

• Express 风格路由注册（get/post/put/delete/patch/all）
• 链式响应 API（status/setHeader/contentType/send/json）
• 同一路径多方法绑定（route）
• 内置 CORS 中间件
• 静态文件服务
• 服务器生命周期事件（onStart/onStop/onRequest/onError）

安装

将插件导入项目 uni_modules 目录即可使用。

基本用法

import { createHttpServer, HttpServerTask, HttpRequest } from "@/uni_modules/xyz-httpserver"

// 创建服务器
const app = createHttpServer({
  port: 8080,
  success: (res) => { console.log('创建成功') },
  fail: (err) => { console.log('创建失败', err.errMsg) },
})

// 注册路由
app.get('/api/hello', (req: HttpRequest) => {
  app.handleRequest(req).json({ msg: "Hello!" })
})

app.post('/api/echo', (req: HttpRequest) => {
  app.handleRequest(req).status(200).json({
    echo: req.body,
    method: req.method,
    path: req.path
  })
})

// 启动服务器
app.start({
  success: () => { console.log('服务器已启动') },
  fail: (err) => { console.log('启动失败', err.errMsg) },
})

API

createHttpServer(options)

创建 HTTP 服务器实例。

返回 HttpServerTask 实例。

HttpServerTask

路由注册

// 单方法注册
app.get(path, handler)
app.post(path, handler)
app.put(path, handler)
app.delete(path, handler)
app.patch(path, handler)
app.all(path, handler)     // 匹配所有方法

// 同一路径多方法
app.route('/api/users')
  .get((req) => { app.handleRequest(req).json({ users: [] }) })
  .post((req) => { app.handleRequest(req).status(201).json({ created: true }) })

handleRequest(req)

在路由 handler 中调用，执行中间件链并返回 HttpResponse 对象。

app.get('/api/data', (req: HttpRequest) => {
  app.handleRequest(req)
    .status(200)
    .setHeader('X-Custom', 'value')
    .json({ data: "ok" })
})

HttpResponse 链式方法

调用 send() 或 json() 后响应自动完成。

生命周期

// 启动
app.start()
app.start({ success, fail, complete })

// 停止
app.stop()
app.stop({ success, fail, complete })

事件监听

app.onStart((result) => {
  console.log(`服务器启动: ${result.host}:${result.port}`)
})

app.onStop((result) => {
  console.log('服务器已停止')
})

app.onRequest((result) => {
  console.log(`${result.request.method} ${result.request.uri}`)
})

app.onError((result) => {
  console.log(`错误 [${result.phase}]: ${result.errMsg}`)
})

内置中间件

CORS

// 默认配置（允许所有来源）
app.useCors()

// 自定义配置
app.useCors({
  allowOrigin: ["http://localhost:3000", "http://example.com"],
  allowMethods: "GET, POST",
  allowHeaders: "*",
  allowCredentials: true,
  maxAge: 86400
})

静态文件

// 所有请求尝试从 sandbox/public 目录查找文件
app.useStatic(uni.env.SANDBOX_PATH + '/public')

// GET /static/css/app.css → 读取 sandbox/www/css/app.css
app.useStatic(uni.env.SANDBOX_PATH + '/www', '/static')

参数说明：

• root：磁盘上的文件根目录
• path（可选）：URL 挂载前缀，默认 "/"。请求 URL 去掉此前缀后的部分作为文件相对路径查找

HttpRequest 对象

错误处理

onError 覆盖框架可控的错误：

用户路由 handler 内的错误需自行处理：

app.get('/api/data', (req: HttpRequest) => {
  try {
    const result = doSomething()
    app.handleRequest(req).json({ data: result })
  } catch (e) {
    app.handleRequest(req).status(500).json({ error: e.message })
  }
})

错误码

完整示例

import { createHttpServer, HttpServerTask, HttpRequest, StartServerOptions, StopServerOptions, GeneralCallbackResult, HttpServerFail } from "@/uni_modules/xyz-httpserver"

let app: HttpServerTask | null = null

function startServer(): void {
  app = createHttpServer({
    port: 8080,
    success: (res) => { 
      console.log('createHttpServer: ok') 
    },
    fail: (err) => { 
      console.log(`createHttpServer fail: ${err.errCode} ${err.errMsg}`) 
    },
  })

  // 中间件
  app!.useCors()
  app!.useStatic(uni.env.SANDBOX_PATH, '/static')

  // 路由
  app!.get('/api/hello', (req: HttpRequest) => {
    app!.handleRequest(req).json({ msg: "Hello from UTS HTTP Server!" })
  })

  app!.post('/api/echo', (req: HttpRequest) => {
    app!.handleRequest(req).json({ echo: req.body })
  })

  app!.post('/api/form', (req: HttpRequest) => {
    let info = ""
    if (req.formParams != null) {
      req.formParams!.forEach((value, key) => { 
        info += `${key}=${value} ` 
      })
    }
    app!.handleRequest(req).json({ received: info })
  })

  // 事件
  app!.onStart((result) => { 
    console.log(`Started on ${result.host}:${result.port}`) 
  })
  app!.onStop(() => { 
    console.log('Stopped') 
  })
  app!.onRequest((result) => { 
    console.log(`>> ${result.request.method} ${result.request.uri}`) 
  })
  app!.onError((result) => { 
    console.log(`Error [${result.phase}]: ${result.errMsg}`) 
  })

  // 启动
  app!.start({
    success: (res) => { 
      console.log('start: ok') 
    },
    fail: (err) => { 
      console.log(`start fail: ${err.errCode} ${err.errMsg}`) 
    },
  })
}

function stopServer(): void {
  app?.stop()
  app = null
}