miniserve 0.35.0 常用 CLI 命令与工具详解
miniserve 0.35.0 日常命令组合手册：匿名/认证分享、上传收集、tar/tar.gz/zip 打包下载、自定义响应头、随机路由、WebDAV、HTTPS、断点续传与健康检查，12 个场景全部实测回显。
miniserveminiserveRust文件服务器文件传输2026/10/30
miniserve 0.35.0 常用 CLI 命令与工具详解
目标：把 miniserve 0.35.0 的日常使用整理成「拿来即跑」的命令手册——从启动/停止、匿名与认证分享，到上传收集、打包下载、WebDAV、HTTPS 与健康检查，每条命令均配 Ubuntu 22.04 实测回显。
一、环境信息
- 操作系统：Ubuntu 22.04.5 LTS（x86_64）
- miniserve：0.35.0（
miniserve --version→miniserve 0.35.0） - 测试目录：
/srv/share（内含hello.txt、README.md、docs/、photos/、upload/、符号链接hello-link、隐藏文件.hidden-file） - 配套工具：curl 7.81.0（认证/上传/打包验证）、openssl（自签证书）、systemd（托管）
- 安装方式：官方 Releases 二进制装于
/usr/local/bin/miniserve（安装过程见《Ubuntu 22.04 安装 miniserve 0.35.0 指南》）
二、工具概览
miniserve 是单命令多旗标形态：没有子命令，一个 miniserve [OPTIONS] [PATH] 加旗标覆盖全部能力，另有两个「打印后退出」的辅助命令。日常配合的工具链：
| 工具 | 角色 | 常用度 |
|---|---|---|
miniserve | 文件服务本体 | 核心 |
curl | 验证下载/认证/上传/打包 | 高 |
systemd | 长期托管（unit + 环境变量） | 高 |
openssl | 自签 TLS 证书（测试） | 中 |
wget | 配合 -W 页脚命令递归下载 | 中 |
miniserve 自身命令矩阵：
| 命令 | 作用 | 是否启动服务 |
|---|---|---|
miniserve --version | 打印版本 | 否 |
miniserve --help / -h | 全量/摘要帮助 | 否 |
miniserve --print-completions <shell> | 生成补全脚本（bash/elvish/fish/powershell/zsh） | 否 |
miniserve --print-manpage | 生成 man 手册 | 否 |
miniserve [OPTIONS] [PATH] | 启动文件服务 | 是 |
GET /__miniserve_internal/healthcheck | 健康检查端点（HTTP） | — |
三、前置条件
# 二进制就绪且版本正确
miniserve --version
实测回显：
miniserve 0.35.0
# 目标端口空闲（无输出即空闲）
netstat -ltn | grep :8080
# 服务目录就绪
ls /srv/share
实测回显：
docs hello-link hello.txt photos README.md upload
四、基础命令详解
4.1 版本与帮助
miniserve --version
miniserve -h | head -8
实测回显：
miniserve 0.35.0
For when you really just want to serve some files over HTTP right now!
Usage: miniserve [OPTIONS] [PATH]
Arguments:
[PATH]
Which path to serve
全量旗标语义与默认值见《miniserve 0.35.0 配置参数详解》，本篇只给日常组合。
4.2 启动与停止
# 前台启动（Ctrl+C 停止）
miniserve /srv/share
# 后台启动并落日志
nohup miniserve /srv/share > /var/log/miniserve.log 2>&1 &
# 停止
pkill -x miniserve
启动横幅逐行解读（实测）：
miniserve v0.35.0 ← 版本
Bound to [::]:8080, 0.0.0.0:8080 ← 实际绑定（默认 v4+v6 全接口）
Serving path /srv/share ← 服务根目录
Available at (non-exhaustive list): ← 可访问地址（非穷举）
http://127.0.0.1:8080
http://172.17.0.2:8080 ← 内网接口地址
http://[::1]:8080
生产环境不跑 nohup，交给 systemd（unit 全文与验证回显见安装指南第八章）。
4.3 补全与 man 手册安装
# bash 补全（官方标准路径）
miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve
mkdir -p ~/.local/share/bash-completion/completions
miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve
wc -l ~/.local/share/bash-completion/completions/miniserve
# man 手册
miniserve --print-manpage > /usr/share/man/man1/miniserve.1
man -f miniserve 2>/dev/null || man miniserve | head -4
实测回显：
289 /root/.local/share/bash-completion/completions/miniserve
miniserve(1) miniserve 0.35.0
⚠️ 注意：补全目录不存在时先
mkdir -p；man 路径写入需要 root。
五、场景化命令组合实测
以下每个场景独立可执行，端口各自错开；curl 命令与回显均为真实运行结果。
5.1 匿名快速分享
miniserve -p 8080 /srv/share
验证目录列表与文件下载：
curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://127.0.0.1:8080/
curl -s http://127.0.0.1:8080/hello.txt
实测回显：
GET / -> 200
hello miniserve
加 ?search= 按名称过滤（大小写不敏感）：
curl -s "http://127.0.0.1:8080/?search=hello" | grep -c "hello.txt"
curl -s "http://127.0.0.1:8080/?search=nomatch_xyz" | grep -c "hello.txt"
实测回显：
1
0
5.2 认证分享（明文 / SHA-256 / 多用户文件）
# 明文：root:q1w2e3r4
miniserve --auth root:q1w2e3r4 -p 8081 /srv/share
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8081/
curl -s -u root:q1w2e3r4 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8081/
curl -s -u root:wrongpass -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8081/
实测回显（401/200/401 边界清晰，未认证响应头 www-authenticate: Basic）：
401
200
401
# 哈希：不在命令行留明文密码
echo -n "q1w2e3r4" | sha256sum
实测回显：
13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9 -
miniserve --auth "admin:sha256:13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9" -p 8082 /srv/share
curl -s -u admin:q1w2e3r4 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8082/
实测回显：
200
# 多用户收敛到文件
printf "root:q1w2e3r4\nadmin:sha256:13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9\n" > /srv/authfile.txt
miniserve --auth-file /srv/authfile.txt -p 8083 /srv/share
curl -s -u root:q1w2e3r4 -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8083/
curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8083/
实测回显：
200
401
5.3 上传收集（手机/浏览器向服务器传文件）
mkdir -p /tmp/ms-up # 暂存目录必须预存在
miniserve --auth root:q1w2e3r4 --upload-files /upload --temp-directory /tmp/ms-up -p 8084 /srv/share
浏览器里访问 http://<服务器>:8084，页面上传面板把文件写到服务目录的 upload/ 子目录。命令行等价验证（浏览器上传接口 = POST /upload?path=<目录>，multipart 字段名 file）：
echo "hello from upload test" > /tmp/up.txt
curl -s -u root:q1w2e3r4 -F "file=@/tmp/up.txt" "http://127.0.0.1:8084/upload?path=/upload" -o /dev/null -w "POST -> %{http_code}\n"
ls /srv/share/upload/ && cat /srv/share/upload/up.txt
实测回显（303 为上传成功后的重定向，文件内容落盘正确）：
POST -> 303
up.txt
hello from upload test
缺 path 参数时的真实报错（排障实录）：
Query deserialize error: missing field `path`
5.4 打包下载（整个目录一键带走）
miniserve -r -g -z -p 8085 /srv/share
curl -s -o /tmp/dl.tar "http://127.0.0.1:8085/?download=tar" -w "tar %{http_code} %{size_download}B\n"
curl -s -o /tmp/dl.tgz "http://127.0.0.1:8085/?download=tar_gz" -w "tar.gz %{http_code} %{size_download}B\n"
curl -s -o /tmp/dl.zip "http://127.0.0.1:8085/?download=zip" -w "zip %{http_code} %{size_download}B\n"
file /tmp/dl.tar | cut -c1-60 && tar tf /tmp/dl.tar | head -3
实测回显（三格式均为真归档，tar 内容可见目录结构）：
tar 200 1319424B
tar.gz 200 1051806B
zip 200 1311895B
/tmp/dl.tar: POSIX tar archive (GNU)
share/
share/hello-link
share/.hidden-file
⚠️ 注意：zip 在内存中生成，超大目录优先用 tar/tar.gz（官方
--help警告）。
5.5 自定义响应头（联调/网关标记）
miniserve --header "X-Made-With:miniserve" --header "Cache-Control:no-cache" -p 8086 /srv/share
curl -s -D- -o /dev/null http://127.0.0.1:8086/hello.txt | grep -iE "HTTP/|x-made|cache-control"
实测回显：
HTTP/1.1 200 OK
cache-control: no-cache
x-made-with: miniserve
5.6 随机路由防扫描
miniserve --random-route -p 8087 /srv/share
cat /var/log/miniserve87.log # 启动横幅中读出随机前缀
实测横幅（每次启动随机）：
Available at (non-exhaustive list):
http://127.0.0.1:8087/10671b
curl -s -o /dev/null -w "GET /10671b -> %{http_code}\n" http://127.0.0.1:8087/10671b
curl -s -o /dev/null -w "GET / -> %{http_code}\n" http://127.0.0.1:8087/
实测回显（根路径 404，随机前缀 307 规范化后可访问）：
GET /10671b -> 307
GET / -> 404
5.7 README 渲染 + 二维码 + wget 页脚
miniserve --readme -q -W -p 8088 /srv/share
curl -s http://127.0.0.1:8088/ | grep -oE "<h1>[^<]*</h1>" | head -1
实测回显（README.md 按 GitHub 风格渲染进页面）：
<h1>项目说明文档</h1>
-q 在页面右上角显示二维码（手机扫码即得地址，适合临时会客/内网演示）；-W 在页脚给出递归下载命令，形如 wget -r -np -nH -R "index.html*" http://<host>:8088，直接复制即用。
5.8 WebDAV 只读浏览
miniserve --enable-webdav -p 8089 /srv/share
curl -s -X PROPFIND -H "Depth: 1" http://127.0.0.1:8089/ -o /dev/null -w "PROPFIND -> %{http_code}\n"
curl -s -X PROPFIND -H "Depth: 1" http://127.0.0.1:8089/ | grep -oE "<D:href>[^<]*</D:href>" | head -5
实测回显（207 Multi-Status 与成员清单，可被 WebDAV 客户端挂载浏览）：
PROPFIND -> 207
<D:href>/</D:href>
<D:href>/docs/</D:href>
<D:href>/hello.txt</D:href>
<D:href>/upload/</D:href>
<D:href>/photos/</D:href>
5.9 HTTPS（自签证书）
openssl req -x509 -newkey rsa:2048 -keyout /srv/ms.key -out /srv/ms.crt -days 30 -nodes -subj "/CN=miniserver.local"
miniserve --tls-cert /srv/ms.crt --tls-key /srv/ms.key -p 8443 /srv/share
curl -sk -D- -o /dev/null https://127.0.0.1:8443/hello.txt | head -2
实测回显（TLS 直挂后自动协商 HTTP/2）：
HTTP/2 200
content-length: 16
5.10 静态站点与 SPA 预览
mkdir -p /srv/site && echo "<h1>SPA home</h1>" > /srv/site/index.html && echo "plain" > /srv/site/about.html
miniserve --spa --index index.html -p 8096 /srv/site
curl -s http://127.0.0.1:8096/notexist | head -1
实测回显（404 回退到 index.html，SPA 路由可接管）：
<h1>SPA home</h1>
miniserve --pretty-urls -p 8097 /srv/site
curl -s -o /dev/null -w "GET /about -> %{http_code}\n" http://127.0.0.1:8097/about
实测回显：
GET /about -> 200
5.11 健康检查、断点续传与访问日志
# 健康检查（监控探针直接用它）
curl -s -o /dev/null -w "healthcheck -> %{http_code} " http://127.0.0.1:8085/__miniserve_internal/healthcheck
curl -s http://127.0.0.1:8085/__miniserve_internal/healthcheck
# Range 断点续传
curl -s -H "Range: bytes=0-4" -D- -o /dev/null http://127.0.0.1:8085/hello.txt | grep -iE "HTTP/|content-range"
curl -s -H "Range: bytes=0-4" http://127.0.0.1:8085/hello.txt
实测回显：
healthcheck -> 200 OK
HTTP/1.1 206 Partial Content
content-range: bytes 0-4/16
hello
# -v 访问日志（排障与简单审计）
miniserve -v -p 8097 /srv/share > /tmp/ms19.log 2>&1 &
curl -s -o /dev/null http://127.0.0.1:8097/about
tail -1 /tmp/ms19.log
实测回显（时间戳 / 级别 / 来源 / 请求 / 状态 / 字节数 / UA / 耗时）：
Fri, 30 Oct 2026 08:13:26 +0000 [INFO] 127.0.0.1 "GET /about HTTP/1.1" 200 6 "-" "curl/7.81.0" 0.000198
5.12 环境变量方式运行
每个旗标都有 MINISERVE_* 环境变量同义形式，适合 systemd Environment= 或多实例差异化：
MINISERVE_PORT=8080 MINISERVE_TITLE="EnvFiles" MINISERVE_ENABLE_TAR=true miniserve /srv/share &
sleep 1
curl -s http://127.0.0.1:8080/ | grep -oE "<title>[^<]*</title>"
pkill -x miniserve
实测回显：
<title>EnvFiles</title>
六、注意事项
- 默认绑定全部接口：不指定
-i时 IPv4+IPv6 全监听（官方 Binding behavior），临时分享敏感目录务必加--auth或-i 127.0.0.1； - 上传目录写权限：以 systemd 专用用户运行时，上传目标目录与
--temp-directory都要归该用户所有，否则上传 403/失败； --temp-directory放磁盘：官方建议别放 tmpfs（内存盘），大文件上传会吃内存；-m不是服务端白名单：媒体类型约束对 curl 直传不拦截（0.35.0 实测），严格管控放网关层；- zip 内存风险：大目录打包用
-r/-g； - 认证密码可见性：明文格式会出现在
ps/shell 历史里，长期服务用username:sha256:hash或--auth-file； - 升级即换二进制：单文件形态升级 = 替换
/usr/local/bin/miniserve+systemctl restart miniserve.service，无需迁移数据。
七、常见问题（FAQ）
Q1：浏览器上传一直 400？
上传接口需要 path 查询参数指向目标子目录（curl 实测缺参报 Query deserialize error: missing field 'path'）。网页端正常情况下自动携带；手工 curl 参照 5.3 节写法。
Q2：启动报 the following required arguments were not provided: --upload-files？
-U/--pastebin/-m/-M/--chmod/-o/--temp-directory 都依赖 --upload-files，必须同用。
Q3：随机路由每次重启都变，下游脚本怎么办？
改用固定 --route-prefix files，横幅与 URL 均稳定；--random-route 只适合人工临时分享。
Q4：访问 / 一直 404 但文件能下载？
检查是否开了 -I/--disable-indexing（列表禁用、直链保留）或 --route-prefix/--random-route（必须带前缀访问）。
Q5：扫码后手机打不开页面？
-q 二维码展示的是 miniserve 探测到的接口地址（非穷举列表第一个可用项），手机与服务器需同网段且防火墙放行端口（ufw allow 8080/tcp）。
Q6：怎么只允许内网访问？
-i 127.0.0.1 只绑回环；-i 172.17.0.2 这类指定接口只绑该地址；systemd 加固模板单元默认 IPAddressAllow=localhost，对外服务需覆盖该指令。
八、参考链接
- 官方 README（How to use 节的搜索/拍照上传等用法）：https://github.com/svenstaro/miniserve （查询日期 2026-10-30）
miniserve --help全量输出：0.35.0 二进制实查（2026-10-30）- 站内认知篇：《miniserve 介绍与选型指南》
- 站内安装篇：《Ubuntu 22.04 安装 miniserve 0.35.0 指南》
- 站内参数篇：《miniserve 0.35.0 配置参数详解》
章节目录