A powerful frontend development server with API proxy, static file serving, and dual-mode static proxy support. Built with Node.js + Express + http-proxy-middleware. 基于 Node.js + Express + http-proxy-middleware 的强大前端开发服务器,支持API代理、静态文件服务和双模式静态代理。
npm install agent-publish-server

基于 Node.js + Express + http-proxy-middleware 的前端服务启动插件,提供强大的代理和静态文件服务能力。
English | 中文
- 🚀 快速启动:一键启动,支持交互式配置
- 🔄 API 代理:灵活的 API 请求代理,支持跨域处理
- 📁 静态代理:支持静态文件服务和 HTTP 服务代理两种模式
- 🌐 双重模式:静态文件代理和 HTTP 服务代理可同时使用
- 📝 访问日志:实时请求日志记录和监控
- ⚡ 路径验证:自动路径存在性检查和验证
- 🛠️ CLI 支持:命令行工具,易于集成到构建流程
- 📋 配置文件:支持 JSON 配置文件,灵活配置各种代理规则
``bash`
npm install agent-publish-server -g
#### 方式一:交互式配置(推荐)
`bash`
agent-publish-server -wp
这将引导您完成交互式设置:
1. 输入端口号
2. 输入项目地址(打包后)
3. 输入代理接口配置(格式:/api:http://localhost:3000)agent_config.json
4. 选择是否继续添加代理(1:继续,0:结束)
5. 生成 并获得启动命令提示
#### 方式二:手动配置
1. 初始化配置文件:
`bash`
agent-publish-server init
2. 编辑生成的 agent_config.json:
`json`
{
"port": 8080,
"dir": "./",
"log": true,
"proxy": {
"/api": {
"target": "http://localhost:3000",
"changeOrigin": true,
"pathRewrite": {
"^/api": ""
}
}
}
}
3. 启动服务:
`bash`
agent-publish-server -c ./agent_config.json
| 选项 | 说明 | 示例 |
| --------------------- | ----------------- | --------------------------------------- |
| -wp, --write-proxy | 交互式代理配置 | agent-publish-server -wp |-c, --config <路径>
| | 指定配置文件路径 | agent-publish-server -c ./config.json |-p, --port <端口>
| | 覆盖端口号 | agent-publish-server -p 3000 |-d, --dir <目录>
| | 覆盖静态文件目录 | agent-publish-server -d ./dist |--log <布尔值>
| | 启用/禁用访问日志 | agent-publish-server --log false |-v, --version
| | 显示版本 | agent-publish-server -v |init
| | 初始化配置文件 | agent-publish-server init |
`typescript`
interface AgentConfig {
port?: number; // 服务器端口(默认:8080)
dir?: string; // 静态文件目录(默认:"./")
redirect?: string; // 根路径重定向,如 "/app" 表示访问 / 时重定向到 /app
fallbackRedirect?: string; // 404兜底重定向,当路由匹配不上时重定向到指定路径
log?: boolean; // 启用访问日志(默认:true)
proxy?: {
// API代理配置
[path: string]: {
target: string; // 目标URL
changeOrigin?: boolean; // 更改源头
pathRewrite?: {
// 路径重写规则
[pattern: string]: string;
};
};
};
staticProxy?: {
// 静态网页代理配置
[path: string]: {
target: string; // 目标URL或本地文件路径
type?: "http" | "static"; // 代理类型(默认:http)
changeOrigin?: boolean; // 更改源头,仅http类型有效(默认:true)
};
};
}
通过 redirect 配置实现访问根路径时自动重定向到指定路径:
`json`
{
"port": 3000,
"redirect": "/app",
"staticProxy": {
"/app": {
"target": "./dist",
"type": "static"
}
}
}
这样配置后,访问 http://localhost:3000/ 会自动重定向到 http://localhost:3000/app。
通过 fallbackRedirect 配置实现当路由匹配不上时自动重定向到指定路径,避免出现黑屏或404页面:
`json`
{
"port": 3000,
"redirect": "/app",
"fallbackRedirect": "/app",
"staticProxy": {
"/app": {
"target": "./dist",
"type": "static"
}
}
}
这样配置后:
- 访问 http://localhost:3000/ 会自动重定向到 /app/unknown
- 访问不存在的路由(如 )也会重定向到 /appstaticProxy
- 已配置的 路径仍正常访问,不受影响
除了 API 代理外,还支持静态网页代理功能,用于代理整个网站或应用。
#### 配置示例
静态文件代理:
`json`
{
"staticProxy": {
"/sub_page": {
"target": "./dist",
"type": "static"
}
}
}
HTTP 服务代理:
`json`
{
"staticProxy": {
"/app": {
"target": "http://localhost:3000",
"type": "http",
"changeOrigin": true
}
}
}
#### 功能特性
- 双重代理模式:支持静态文件代理和 HTTP 服务代理
- 静态文件代理:直接代理到本地文件系统目录
- HTTP 服务代理:代理到远程 HTTP 服务,支持路径重写
- 自动路径处理:自动处理代理路径前缀
- 优先级处理:静态代理优先于默认静态文件服务
- 路径验证:自动检查静态文件路径是否存在
#### 与 API 代理组合使用
staticProxy 可以与 proxy 配置同时使用:
`json`
{
"proxy": {
"/api": {
"target": "http://localhost:3000",
"changeOrigin": true,
"pathRewrite": { "^/api": "" }
}
},
"staticProxy": {
"/dist_files": {
"target": "./dist",
"type": "static"
},
"/remote_app": {
"target": "http://localhost:3001",
"type": "http",
"changeOrigin": true
}
}
}
这样配置后:
- 访问 /api/ 会代理到 http://localhost:3000/(API 服务)/dist_files/*
- 访问 会访问本地 ./dist 目录下的静态文件/remote_app/
- 访问 会代理到 http://localhost:3001/(远程应用)
- 其他路径会访问默认静态文件目录
访问日志默认启用,显示内容包括:
- 时间戳(ISO 格式)
- 客户端 IP 地址
- HTTP 方法和 URL
- 用户代理字符串
日志输出示例:
``
[2025-08-27T11:02:48.854Z] ::1 "GET /" "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36"
禁用日志:
`bash``
agent-publish-server --log false
- 项目路径无效:显示"项目路径错误"并退出
- 端口号无效:验证端口号范围(1-65535)
- 配置缺失:使用默认配置
- React/Vue 开发:为构建后的应用提供服务并代理 API
- 前端测试:快速静态文件服务,处理跨域问题
- 本地开发:代理 API 调用到后端服务
- SPA 部署:为单页应用提供正确的路由支持
- 微前端架构:通过静态代理整合多个前端应用
- 开发环境整合:将多个本地服务统一到一个端口访问
- v1.0.27: 新增404兜底重定向配置(fallbackRedirect),当路由匹配不上时自动重定向到指定路径,避免黑屏或404错误
- v1.0.26: 新增根路径重定向配置(redirect),支持访问 / 时自动跳转到指定路径
- v1.0.25: 修复 staticProxy static 类型不支持 SPA History 路由刷新的问题,添加自动 fallback 到 index.html 支持
- v1.0.24: 修复移动端兼容性问题,优化 HTTP 响应头设置,确保 iOS 和 Android 显示一致性
- v1.0.23: 完善双语文档支持,优化 package.json 关键词,提升 npm 包曝光度
- v1.0.22: 优化和完善 staticProxy 功能,提升稳定性
- v1.0.18: 增强 staticProxy 功能,支持静态文件代理和 HTTP 服务代理两种模式
- v1.0.17: 新增静态网页代理功能(staticProxy),支持与 API 代理同时使用
- v1.0.16: 新增交互式配置、访问日志、路径验证功能
- v1.0.15: 基础代理和静态文件服务功能
MIT License
欢迎提交 Issue 和 Pull Request!