@up-cli/app-core

Node.js 静态服务器核心模块，支持静态文件托管、History 模式和代理转发。

安装

pnpm add @up-cli/app-core

使用

import { run } from '@up-cli/app-core'

await run({
  server: {
    port: 3000,
    publicPath: 'dist',
    historyMode: true,
  },
})

配置文件

在项目根目录创建 up.config.json，启动时自动加载：

{
  "server": {
    "port": 3000,
    "host": "0.0.0.0",
    "publicPath": "public",
    "basePath": "",
    "historyMode": true
  },
  "proxy": {
    "enabled": false,
    "rules": []
  }
}

配置优先级：代码传参 > 配置文件 > 默认值

server

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | port | number | 3000 | 服务端口（1-65535） | | host | string | 0.0.0.0 | 服务主机地址 | | publicPath | string | public | 静态文件目录 | | basePath | string | "" | 基础路径 | | historyMode | boolean | true | 是否启用 History 模式 |

proxy

| 字段 | 类型 | 默认值 | 说明 | |------|------|--------|------| | enabled | boolean | false | 是否启用代理 | | rules | ProxyRule[] | [] | 代理规则列表 |

ProxyRule

| 字段 | 类型 | 必填 | 说明 | |------|------|------|------| | path | string | 是 | 代理路径前缀 | | target | string | 是 | 目标地址（合法 URL） | | changeOrigin | boolean | 否 | 是否改变源 | | ws | boolean | 否 | 是否支持 WebSocket | | pathRewrite | Record<string, string> | 否 | 路径重写规则 | | headers | Record<string, string> | 否 | 自定义请求头 |

代理配置示例

{
  "proxy": {
    "enabled": true,
    "rules": [
      {
        "path": "/api",
        "target": "http://localhost:8080",
        "changeOrigin": true,
        "pathRewrite": { "^/api": "" }
      }
    ]
  }
}

fileRoutes（文件路由）

支持在 TAF 环境下从配置中心加载文件内容并映射到 HTTP 路径。

{
  "fileRoutes": [
    { "path": "/api/config", "tafFileName": "app-config.json" },
    { "path": "/api/whitelist", "tafFileName": "whitelist.txt" }
  ]
}

| 字段 | 类型 | 说明 | |------|------|------| | path | string | HTTP 请求路径（精确匹配） | | tafFileName | string | TAF 配置中心的文件名 |

工作流程：

1. 服务启动时读取 fileRoutes 配置
2. 在 TAF 环境下，通过 @taf/taf-config 加载文件内容到内存
3. 自动推断 Content-Type（.json → application/json，.txt → text/plain）
4. 精确匹配路径后返回对应内容
5. 非 TAF 环境下 fileRoutes 不生效

API

run(options?)

启动服务器。

import { run } from '@up-cli/app-core'

await run({
  root: process.cwd(),
  configFile: 'up.config.json',
  server: { port: 3000 },
  proxy: { enabled: false },
  fileRoutes: []
})

参数说明：

| 参数 | 类型 | 说明 | |------|------|------| | root | string | 项目根目录（默认：process.cwd()） | | configFile | string | 配置文件路径（默认：up.config.json） | | server | Partial<ServerConfig> | 服务器配置覆盖 | | proxy | Partial<ProxyConfig> | 代理配置覆盖 | | fileRoutes | FileRouteRule[] | 文件路由配置覆盖 |

createApp(options)

创建 Koa 应用实例（高级用法）。

import { createApp } from '@up-cli/app-core'

const app = createApp({
  config: upConfig,
  root: process.cwd(),
  fileRouteMap: new Map()
})

isTafEnv()

判断是否为 TAF 环境。

import { isTafEnv } from '@up-cli/app-core'

if (isTafEnv()) {
  // TAF 环境特定逻辑
}

类型导出

import type {
  FileRouteRule,
  ProxyConfig,
  ProxyRule,
  RunOptions,
  ServerConfig,
  UpConfig,
  UpConfigFile,
} from '@up-cli/app-core'