vue-httpd

一个极简的命令行静态文件服务器，专为 Vue 单页应用打包后的预览而设计。

背景

Vue 项目打包后生成的是静态文件，以前可以直接双击 index.html 在浏览器中预览。但随着浏览器安全策略越来越严格（如 CORS、文件协议限制等），本地直接打开会遇到各种问题。vue-httpd 就是为了解决这个问题而生的——一键将当前目录作为静态服务器运行，并自动支持单页应用的路由回退。

特性

• 零配置启动 - 进入目录，一条命令即可运行
• 默认端口 6006 - 端口被占用时自动向上递增
• SPA 路由支持 - 访问不存在的路径自动回退，支持自定义 fallback 文件，完美支持 Vue Router 的 history 模式
• 自动显示访问地址 - 启动后同时输出本地地址和局域网地址，方便手机/其他设备预览
• 零依赖 - 纯 Node.js 原生实现，无需安装任何第三方包

安装

npm install -g vue-httpd

或者本地临时试用：

npx vue-httpd

用法

基本用法

在当前目录启动服务：

vue-httpd

输出示例：

  服务已启动
  静态目录: D:\project\my-vue-app\dist
  回退文件: index.html

  本地:   http://localhost:6006/
  网络:   http://192.168.1.100:6006/

  按 Ctrl+C 停止服务

指定目录

vue-httpd ./dist

指定端口

vue-httpd --port 8080

如果 8080 被占用，会自动尝试 8081、8082……

指定回退文件

vue-httpd --fallback app.html

如果 app.html 不存在，会自动尝试 index.html；如果还没有，则尝试目录下任意一个 .html 文件。

组合使用

vue-httpd --port 3000 ./dist
vue-httpd --port 8080 --fallback app.html ./dist

命令行参数

| 参数 | 简写 | 说明 | 默认值 | |------|------|------|--------| | --port | -p | 指定服务器端口 | 6006 | | --dir | -d | 指定静态文件目录 | 当前工作目录 | | --fallback | -f | 指定回退文件，找不到时自动尝试 index.html 或任意 html | index.html | | --help | -h | 显示帮助信息 | - |

完整示例

假设你已经有一个 Vue 项目并打包完成：

# 进入打包输出目录
cd my-vue-app/dist

# 启动预览服务
vue-httpd

# 或指定端口
vue-httpd -p 8080

然后在浏览器中访问输出的地址即可。

工作原理

1. 启动 HTTP 服务器，监听指定端口
2. 收到请求时，在静态目录中查找对应的文件
3. 如果文件存在，直接返回
4. 如果文件不存在（如 /user/profile），按以下优先级回退：
   • 配置的 --fallback 文件（默认 index.html）
   • 若未配置或找不到，尝试 index.html
   • 若仍找不到，尝试目录下任意一个 .html 文件
   • 若都没有，返回 404
5. 浏览器加载回退文件后，Vue Router 接管并渲染对应页面

适用场景

• Vue / React / Angular 等单页应用打包后本地预览
• 快速搭建本地静态文件服务器
• 局域网内多设备预览（手机、平板等）
• 验证生产构建结果

环境要求

• Node.js >= 12.0.0

License

ISC