# servit

**Repository Path**: hyjiacan/servit

## Basic Information

- **Project Name**: servit
- **Description**: 双击即用的本地多端口静态服务器，自带示例，零安装，优雅退出。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-11
- **Last Updated**: 2026-10-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Servit

> 双击即用的本地多端口静态服务器，自带示例，零安装，优雅退出。

Servit 是一个**单文件、免安装、双击即用**的本地 HTTP 服务器。它解决一个具体问题：**双击 HTML 用 `file://` 协议打开时，Ajax 请求会被浏览器拦截。**

Servit 在本地起 `http://` 服务，让浏览器把页面当成正常网页，Ajax 就能正常发送。它采用**多目录多端口**模型：每个一级子目录独立服务、独立端口；根目录提供所有子目录的索引；每个子目录可通过 `servit.conf` 自定义标题、描述和端口。内置示例和帮助，第一次双击就能看到东西、看到用法。

---

## 特性

- **双击即用** — 不需要命令行，不需要任何环境
- **单文件** — 编译产物就是一个可执行文件，无依赖
- **多目录多端口** — 每个一级子目录独立服务、独立端口
- **自带索引页** — 根目录实时列出所有子目录、标题、描述、地址
- **可自定义** — 子目录下放 `servit.conf` 可设标题、描述、端口
- **自带示例** — 首次运行自动释放内置示例和帮助
- **端口自动切换** — 未指定端口的单元被占用时自动递增
- **CORS 支持** — 默认加上跨域响应头，省掉调试麻烦
- **访问日志** — 控制台实时显示每条请求
- **局域网可访问** — 打印本机局域网地址，手机可测
- **SPA 友好** — 可选路由回退到 `index.html`
- **优雅退出** — `Ctrl+C` 后等待进行中的请求完成再退出

---

## 快速开始

### 方式一：双击

1. 下载 `servit.exe`
2. 放到任意空文件夹
3. 双击

它会自动：

- 释放内置示例到 `www/`
- 扫描子目录，分配端口
- 启动所有服务
- 打开浏览器

把你的 HTML、JS、CSS、JSON 丢进 `www/` 下新建的文件夹里，刷新索引页即可看到。

### 方式二：命令行

```bash
servit                      # 全默认
servit -port 9000           # 根端口 9000，未指定端口的子目录从 9001 起
servit -dir ./projects      # 指定总目录
servit -no-open             # 只起服务，不开浏览器
servit -h                   # 查看完整帮助
```

---

## 命令行参数

| 参数 | 类型 | 默认 | 说明 |
|------|------|------|------|
| `-port` | int | `8080` | 根目录端口，被占用自动递增；未指定端口的子目录从其后依次分配 |
| `-dir` | string | `exe目录/www` | 总目录，其下每个一级子目录各起一个服务 |
| `-no-open` | bool | `false` | 不自动打开浏览器 |
| `-spa` | bool | `false` | 每个单元开启 SPA 路由回退 |
| `-cors` | bool | `true` | 开启 CORS 响应头 |
| `-shutdown-timeout` | int | `5` | 优雅退出等待秒数，超时强制关闭 |
| `-h` / `--help` | - | - | 显示帮助 |

---

## 目录结构

```
servit/
├── servit.exe        # 程序本体
└── www/              # 默认总目录（首次运行自动生成）
    ├── demo/         # 内置 Ajax 示例，独立端口
    │   ├── servit.conf
    │   ├── index.html
    │   ├── data.json
    │   └── style.css
    └── help/         # 内置使用帮助，独立端口
        ├── servit.conf
        ├── index.html
        └── style.css
```

- 默认总目录为 `www/`，位于**可执行文件同目录**
- 可用 `-dir` 参数覆盖
- `www/` 已存在时**不会覆盖**，直接以其为服务根
- 每个一级子目录独立服务、独立端口
- 根目录本身也占一个端口，提供所有子目录的索引页

---

## 自定义配置 `servit.conf`

每个子目录下可放一个 `servit.conf`：

```
title=我的项目
desc=这是一个演示
port=9001
```

- 三个 key 全部可选，顺序任意
- 空行和 `#` 开头的行忽略
- key / value 两侧空白自动去除
- `port` 必须是 1–65535 的整数，非法则忽略

**端口指定规则：**

| 情况 | 行为 |
|------|------|
| 写了 `port`，端口空闲 | 用该端口 |
| 写了 `port`，端口被占 | 报错退出 |
| 两个单元写了同一端口 | 报错退出 |
| 没写 `port` | 从 `-port` 起依次分配，跳过已占用 |
| `port` 值非法 | 忽略，走默认分配 |

**标题和描述：**

- 写了 `title` → 索引页显示该标题，否则用目录名
- 写了 `desc` → 索引页显示该描述，否则不显示描述

---

## 输出示例

启动时，终端只打印首页地址：

```
Servit 已启动

  http://localhost:8080
  http://127.0.0.1:8080
  http://192.168.1.5:8080

总目录: /path/to/www
按 Ctrl+C 优雅退出
```

浏览器打开的索引页则列出每个子目录，含标题、描述、地址。

运行中，每条请求带端口前缀：

```
[8080] GET /            200 0s
[8081] GET /data.json   200 1ms
[8082] GET /            200 0s
```

退出时：

```
^C
正在优雅退出...
[8082] 已停止
[8081] 已停止
[8080] 已停止
已退出，感谢使用 Servit。
```

---

## 从源码构建

需要 Go 1.21+。

```bash
git clone <repo>
cd servit
go build -o servit.exe .
```

交叉编译（在 Mac/Linux 上给 Windows 编译）：

```bash
GOOS=windows GOARCH=amd64 go build -o servit.exe .
```

---

## 常见问题

### 为什么需要它？

浏览器出于安全，禁止 `file://` 协议下的页面发送 Ajax 请求。双击 HTML 文件时，任何 `fetch` 或 `XMLHttpRequest` 都会失败。Servit 在本地起 `http://` 服务，绕过这个限制。

### 多端口是什么意思？

Servit 扫描总目录下的每个一级子目录，**为每个子目录单独起一个服务、单独占一个端口**。根目录本身也占一个端口，并提供所有子目录的索引。这样做的好处是每个子目录完全独立，互不干扰，适合同时调试多个项目。

### 端口被占用怎么办？

未指定端口的单元会自动往后找可用端口，启动时会在控制台告诉你每个单元实际用了哪个。但如果 `servit.conf` 里显式指定了端口，被占用就会报错退出——因为那是你明确指定的。

### CORS 是什么？为什么默认开？

如果你的页面请求的是**另一个**端口或域名的后端，浏览器会拦截。Servit 默认给所有响应加上 `Access-Control-Allow-Origin: *`，省掉这部分调试麻烦。可以用 `-cors=false` 关闭。

### 手机能访问吗？

能。启动时控制台会打印首页的局域网地址（如 `http://192.168.1.5:8080`）。手机连同一 WiFi，浏览器打开即可。索引页里的每个子目录地址也都能点。

### 想重新释放内置示例？

删掉 `www/` 目录，再双击 `servit.exe`。

### 怎么退出？

在控制台按 `Ctrl+C`。Servit 会优雅退出：停止接受新连接，等待进行中的请求完成，然后关闭。默认最多等 5 秒，超时强制关闭。连按两次 `Ctrl+C` 可立即退出。

### 首次运行 Windows 防火墙弹窗？

允许即可。Servit 只监听本地和局域网，不对外网开放。

### `-dir` 的相对路径相对于哪里？

相对于**当前工作目录**。双击时就是 exe 所在目录；命令行时是你所在的那个目录。

---

## 技术栈

- 语言：Go
- 依赖：仅标准库（`net/http`、`embed`、`flag` 等）
- 打包：`go:embed` 嵌入静态资源

---

## 许可证

MIT

---

## 一句话

**把 `servit.exe` 丢进文件夹，双击，Ajax 就能跑了。**