# tinyserver

**Repository Path**: imlzw/tinyserver

## Basic Information

- **Project Name**: tinyserver
- **Description**: `tinyserver` 是一个使用 Go 编写的轻量级命令行静态文件服务器。它可以用一个小型可执行文件把本地目录通过 HTTP 暴露出来，适合临时文件预览、局域网文件共享、前端静态产物检查，以及不想安装 nginx 时的简单静态服务场景。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-21
- **Last Updated**: 2026-05-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# tinyserver

`tinyserver` 是一个使用 Go 编写的轻量级命令行静态文件服务器。它可以用一个小型可执行文件把本地目录通过 HTTP 暴露出来，适合临时文件预览、局域网文件共享、前端静态产物检查，以及不想安装 nginx 时的简单静态服务场景。

## 功能特性

- 从任意本地目录提供静态文件访问。
- 当目录中没有 `index.html` 时，使用 Go 标准库的目录列表页面。
- 仅依赖 Go 标准库，部署时只需要一个二进制文件。
- 支持命令行参数和 `tinyserver.json` 配置文件。
- 支持 `addr` 或 `host` + `port` 两种监听地址配置方式。
- 输出每个 HTTP 请求的时间、方法、路径、状态码、响应字节数和耗时。

## 环境要求

- Go 1.21 或更高版本。

查看当前 Go 版本：

```powershell
go version
```

## 快速开始

在当前目录启动服务，默认监听 `0.0.0.0:8080`：

```powershell
go run .
```

启动后会输出类似内容：

```text
Serving D:\path\to\current\dir
Listening on 0.0.0.0:8080
Open http://localhost:8080/
Press Ctrl+C to stop.
```

访问输出中的 URL 即可浏览文件。

## 命令行用法

指定要提供访问的目录：

```powershell
go run . -dir D:\path\to\files
```

也可以把目录作为位置参数传入：

```powershell
go run . D:\path\to\files
```

修改端口：

```powershell
go run . -port 9000
```

指定监听主机和端口：

```powershell
go run . -host 127.0.0.1 -port 9000
```

直接指定完整监听地址：

```powershell
go run . -addr 127.0.0.1:9000
```

使用指定配置文件：

```powershell
go run . -config .\tinyserver.json
```

查看版本：

```powershell
go run . -version
```

`-addr` 不能和 `-host` 或 `-port` 同时使用。需要监听所有网卡时可以使用默认的 `0.0.0.0:8080`；只允许本机访问时可以使用 `127.0.0.1:8080`。

## 构建

构建当前平台的可执行文件：

```powershell
go build -o tinyserver.exe .
```

运行构建后的程序：

```powershell
.\tinyserver.exe -dir D:\path\to\files -port 9000
```

## 跨平台构建

PowerShell 脚本会默认构建 Windows、Linux 和 macOS 的 `amd64`、`arm64` 产物，并输出到 `dist/`：

```powershell
.\scripts\build.ps1
```

指定版本号：

```powershell
.\scripts\build.ps1 -Version 1.0.0
```

在 Linux 或 macOS 上使用 POSIX shell 脚本：

```sh
./scripts/build.sh
```

指定版本号：

```sh
VERSION=1.0.0 ./scripts/build.sh
```

也可以通过环境变量调整输出目录和目标平台：

```sh
OUT_DIR=dist TARGETS="linux/amd64 linux/arm64" ./scripts/build.sh
```

`dist/` 属于生成目录，通常不需要提交到版本库。

## 配置文件

如果工作目录中存在 `tinyserver.json`，程序会自动加载它。也可以通过 `-config` 显式指定其他 JSON 配置文件。

配置示例见 `tinyserver.example.json`：

```json
{
  "dir": ".",
  "host": "0.0.0.0",
  "port": 8080
}
```

也可以使用 `addr` 一次性指定完整监听地址：

```json
{
  "dir": "D:\\path\\to\\files",
  "addr": "0.0.0.0:8080"
}
```

支持的配置字段：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `dir` | string | 要提供访问的根目录。为空时使用当前目录。 |
| `addr` | string | 完整监听地址，例如 `0.0.0.0:8080`。设置后会覆盖 `host` 和 `port`。 |
| `host` | string | 监听主机。未设置 `addr` 时使用。 |
| `port` | number | 监听端口。未设置 `addr` 时使用，合法范围为 `1` 到 `65535`。 |

配置文件会拒绝未知字段。如果 JSON 中写入未支持的字段，程序会启动失败并提示解析错误。

## 参数优先级

运行时配置按以下顺序合并，越靠后的优先级越高：

1. 默认值：`dir` 为 `.`，`host` 为 `0.0.0.0`，`port` 为 `8080`。
2. `tinyserver.json` 或 `-config` 指定的配置文件。
3. 命令行参数，例如 `-dir`、`-addr`、`-host`、`-port`。
4. 位置目录参数，例如 `tinyserver.exe D:\path\to\files`。

示例：

```powershell
.\tinyserver.exe -config .\tinyserver.json -port 9000 D:\public
```

上面的命令会使用配置文件中的基础配置，端口被命令行覆盖为 `9000`，目录最终被位置参数覆盖为 `D:\public`。

## 请求日志

每个请求会输出一行日志：

```text
2026-05-21T15:08:00+08:00 GET /hello.txt 200 16 1ms
```

字段依次为：

- 请求完成时间。
- HTTP 方法。
- 请求路径。
- HTTP 状态码。
- 响应字节数。
- 请求耗时。

## 测试

运行全部测试：

```powershell
go test ./...
```

测试覆盖了默认配置解析、`host` + `port` 地址解析、未知配置字段拒绝，以及静态文件响应行为。

## 项目结构

```text
.
├── main.go                   # 主程序、配置解析和 HTTP 服务
├── main_test.go              # 单元测试和 HTTP 行为测试
├── tinyserver.example.json   # 配置文件示例
├── scripts/
│   ├── build.ps1             # PowerShell 跨平台构建脚本
│   └── build.sh              # POSIX shell 跨平台构建脚本
└── dist/                     # 构建产物输出目录
```

## 注意事项

- `tinyserver` 不提供认证、鉴权或 TLS，建议只在可信网络或本机开发场景中使用。
- 监听 `0.0.0.0` 会让同一网络中可访问该机器端口的设备访问服务。
- 公开敏感目录前请先确认目录内容，避免暴露私钥、配置文件或个人数据。
- 本地运行配置文件通常命名为 `tinyserver.json`；不要在示例文档中记录个人本地路径。