miniserve 0.35.0 配置参数详解

目标：逐项详解 miniserve 0.35.0 全部命令行旗标与同义环境变量的语义、默认值和依赖关系，作为「miniserve 没有配置文件，一切靠旗标」这一设计下的配置权威速查，全部默认值与回显来自 0.35.0 实查。

一、环境信息

• 操作系统：Ubuntu 22.04.5 LTS（x86_64）
• miniserve 版本：0.35.0（miniserve --version → miniserve 0.35.0）
• 参数来源：miniserve --help 全量输出（379 行实查，2026-10-30），辅以官方 README
• 环境变量机制：0.35.0 的每一个旗标都有同义环境变量，可直接替代命令行注入

二、前置条件

本篇参数均可独立执行验证，仅需 miniserve 二进制就绪：

miniserve --version

实测回显：

miniserve 0.35.0

💡 说明：miniserve 没有配置文件（无 miniserve.conf 之类机制），启动时参数只能来自旗标与环境变量；长期服务用 systemd unit 的 ExecStart/Environment 固化，见《Ubuntu 22.04 安装 miniserve 0.35.0 指南》第八章。

三、参数查看与修改方式

3.1 三种查看途径

# 全量长帮助（每个旗标带说明、默认值与环境变量名）
miniserve --help

# 短摘要帮助
miniserve -h

# 生成 man 手册后用 man 阅读
miniserve --print-manpage > /usr/share/man/man1/miniserve.1 && man miniserve | head -8

man 实测回显（节选）：

miniserve(1)                miniserve 0.35.0               miniserve(1)

NAME
       miniserve - For when you really just want to serve some files
       over HTTP right now!

3.2 修改方式

1. 命令行旗标：即时生效于本次进程；
2. 环境变量：语义与旗标完全等价（如 MINISERVE_PORT=9000 miniserve /srv/share 等价 -p 9000），systemd 场景用 Environment= 注入；
3. 旗标与环境变量同时给出时旗标优先。

四、参数总览

全旗标速查表（默认值一列为 0.35.0 实查值）：

⚠️ 注意一个拼写特例：--temp-directory 的环境变量是 MINISERVER_TEMP_UPLOAD_DIRECTORY（多了 ER），其余全部为 MINISERVE_ 前缀——0.35.0 --help 原文如此，用错拼写不会报错但配置不生效。

关键差异解读：表中标「关/开」的布尔旗标一旦给出即翻转默认行为；带值旗标的默认值即不传时的行为。依赖关系上，--media-type/--raw-media-type/--mkdir/--pastebin/--on-duplicate-files/--chmod/--web-upload-files-concurrency/--temp-directory/--rm-files 都要求先开启 --upload-files（或对应删除场景的 --rm-files），否则 CLI 直接报错退出。

五、核心参数分类详解

5.1 服务基础：端口、接口与 worker

-p/--port、-i/--interfaces、--workers 决定服务怎么暴露。默认绑定全部接口的 IPv4+IPv6（官方「Binding behavior」节），显式给 -i 时只绑指定接口：

# 只绑本机回环，端口 9000，worker 8
miniserve -p 9000 -i 127.0.0.1 --workers 8 /srv/share

启动横幅实测回显（对照默认 4 worker 的另一实例）：

miniserve v0.35.0
Bound to [::]:8080, 0.0.0.0:8080
Serving path /srv/share
Available at (non-exhaustive list):
    http://127.0.0.1:8080
    http://172.17.0.2:8080
    http://[::1]:8080

-i 可多次指定同时绑定多个接口；--workers 影响并发吞吐，小文件高并发场景可适当调大。

5.2 认证：--auth 三种格式与 --auth-file

-a/--auth 支持三种格式（--help 原文）：username:password、username:sha256:hash、username:sha512:hash。可重复多次声明多个用户：

# 明文格式
miniserve --auth root:q1w2e3r4 /srv/share

# sha256 格式（q1w2e3r4 的 sha256）
echo -n "q1w2e3r4" | sha256sum

实测回显：

13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9  -

miniserve --auth "admin:sha256:13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9" /srv/share

认证行为实测（401/200 边界）：

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。多用户交由文件管理（每行一个用户，格式同 --auth，bill: 空密码写法合法）：

printf "root:q1w2e3r4\nadmin:sha256:13a5c202e320d0bf9bb2c6e2c7cf380a6f7de5d392509fee260b809c893ff2f9\n" > /srv/authfile.txt
miniserve --auth-file /srv/authfile.txt -p 8083 /srv/share

实测回显（root 可过、无凭据 401）：

200
401

💡 技术拓展：HTTP 认证不只是 Basic 一族。常见选项对比——

方案	特点	适用场景
Basic（miniserve 所用）	简单、浏览器原生弹窗、密码每次随请求传输（依赖 TLS 保护）	内网/临时分享
Digest	挑战-响应，不传明文密码	遗留系统
Token/Bearer	无状态令牌，常配 API	开放 API
OAuth2/OIDC	第三方身份联邦	面向用户的产品

miniserve 定位临时文件服务，采用 Basic 并支持服务端哈希存储，是能力与复杂度的务实折中；要更强的身份体系请选 filebrowser 一类带用户管理的平台。

5.3 上传与写操作族

这一族旗标最多，且都挂在 --upload-files 之下。-u/--upload-files 可选参数是相对于服务目录的 URL 路径而非物理路径：服务目录为 /srv/share 时给 /upload 指允许写到 /srv/share/upload。

mkdir -p /tmp/ms-up   # --temp-directory 要求目录预存在！
miniserve --auth root:q1w2e3r4 --upload-files /upload \
  --temp-directory /tmp/ms-up --chmod 0644 \
  --on-duplicate-files rename -p 8084 /srv/share

不预建暂存目录时的真实报错（实测）：

error: invalid value '/tmp/ms-up' for '--temp-directory <TEMP_UPLOAD_DIRECTORY>': Upload temporary directory must exist and be a directory.

重名策略实测（-o rename 时同名文件自动加后缀 -1）：

curl -s -u root:q1w2e3r4 -F "file=@/tmp/x.jpg" "http://127.0.0.1:8084/upload?path=/upload" -o /dev/null -w "%{http_code}\n"
curl -s -u root:q1w2e3r4 -F "file=@/tmp/x.jpg" "http://127.0.0.1:8084/upload?path=/upload" -o /dev/null -w "%{http_code}\n"
ls /srv/share/upload/

实测回显：

303
303
x-1.jpg
x.jpg

浏览器上传接口要求 path 查询参数（实测缺参报 Query deserialize error: missing field 'path'），完整 curl 写法即上例。-m/--media-type 声明可上传媒体类型（image/audio/video），其约束主要作为浏览器文件选择器的 accept 提示下发——实测 0.35.0 用 curl 直接 POST .txt 文件到 -m image 实例仍返回 303 并落盘，服务端未拦截，不能把它当安全白名单用。-M/--raw-media-type 直接给 MIME 表达式，同理。-R/--rm-files 开启页面删除能力，同样可限定子目录。--directory-size 让列表递归统计目录大小（IO 敏感，大目录慎开）。

5.4 归档下载族：-r / -g / -z / -C

三个归档旗标相互独立、可叠加，分别对应页面上的 tar、tar.gz、zip 下载入口：

miniserve -r -g -z /srv/share

实测下载验证（?download= 查询参数即打包端点）：

curl -s -o /tmp/dl.tar "http://127.0.0.1:8085/?download=tar" -w "%{http_code}\n"
curl -s -o /tmp/dl.tgz "http://127.0.0.1:8085/?download=tar_gz" -w "%{http_code}\n"
curl -s -o /tmp/dl.zip "http://127.0.0.1:8085/?download=zip" -w "%{http_code}\n"
file /tmp/dl.tar /tmp/dl.tgz /tmp/dl.zip

实测回显：

200
200
200
/tmp/dl.tar: POSIX tar archive (GNU)
/tmp/dl.tgz: gzip compressed data, last modified: Fri Oct 30
/tmp/dl.zip: Zip archive data, at least v2.0 to extract

--help 官方警告：zip 在内存中生成、无法流式发送，大目录 zip 可能 OOM；tar/tar.gz 可流式。-C/--compress-response 是 HTTP 响应体压缩（对文本类收益大），官方明确提示有 CPU 开销、默认关闭。

5.5 列表展示族

--header 实测：

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 "x-made|cache-control"

实测回显：

x-made-with: miniserve
cache-control: no-cache

已存在的响应头不会被 --header 覆盖（--help 原文说明）。

5.6 站点形态族：--index / --spa / --pretty-urls / --route-prefix

miniserve --index index.html --spa -p 8096 /srv/site

实测：GET / 直接返回 index.html 内容；访问不存在的路径 GET /notexist 也回退到 index.html（SPA 路由接管 404）。--pretty-urls 开启后 /about 等价 /about.html（两者实测均 200）。--route-prefix 给全部路由加前缀（反代场景对齐上游路径）：

miniserve --route-prefix files -p 8094 /srv/share
curl -s -o /dev/null -w "GET / -> %{http_code} | " http://127.0.0.1:8094/
curl -s -o /dev/null -w "GET /files/ -> %{http_code}\n" http://127.0.0.1:8094/files/

实测回显：

GET / -> 404 | GET /files/ -> 200

--random-route 自动生成 6 位十六进制前缀（实测 /10671b），访问根路径 404、必须带前缀访问，用于规避扫描器，实测 GET /10671b 返回 307（规范化到 /10671b/）后 200。

5.7 传输安全：--tls-cert / --tls-key

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

实测回显：

HTTP/2 200
content-length: 16

同时给出证书与私钥即启用 HTTPS（自动协商 HTTP/2）；缺任一参数则纯 HTTP。生产环境应使用 CA 签发证书或由前置网关终结 TLS。

5.8 主题与辅助输出

-c/--color-scheme 与 -d/--color-scheme-dark 各接受 5 个值（0.35.0 实查）：squirrel（浅色默认）、archlinux（深色默认）、ayu-dark、zenburn、monokai。--log-color 控制日志着色（auto/always/never），systemd 收日志建议 --log-color never 避免转义序列入库。

辅助输出族不启动服务、打印后即退出：

miniserve --print-completions bash | wc -l
miniserve --print-manpage | wc -l

实测回显：

289
342

bash 补全落盘（官方 README 给的标准路径）：

miniserve --print-completions bash > ~/.local/share/bash-completion/completions/miniserve

六、环境变量全表与生产注入

除 --print-completions/--print-manpage 外每个旗标都有环境变量（总览表第三列）。systemd 生产注入示例（/etc/systemd/system/miniserve.service 片段）：

[Service]
User=miniserve
Environment=MINISERVE_PORT=8080
Environment=MINISERVE_TITLE=Files
Environment=MINISERVE_ENABLE_TAR=true
Environment="MINISERVE_TITLE=hello world"
Environment=MINISERVER_TEMP_UPLOAD_DIRECTORY=/tmp/ms-up
ExecStart=/usr/local/bin/miniserve /srv/share

逐项说明：布尔旗标的环境变量给 true 即开启；含空格的值整体加引号；MINISERVER_TEMP_UPLOAD_DIRECTORY 拼写特例见第四章 ⚠️。修改后 systemctl daemon-reload && systemctl restart miniserve.service 生效。环境变量方式便于「同一 ExecStart、多实例不同配置」的模板化运维。

七、生产启动参数模板

适用场景：内网文件分发服务器（2C4G、SATA/NVMe 均可、服务目录在本地盘）。unit 的 ExecStart 推荐组合：

/usr/local/bin/miniserve \
  --auth-file /etc/miniserve/authfile \
  --upload-files /upload \
  --temp-directory /var/tmp/miniserve-upload \
  --chmod 0644 \
  --on-duplicate-files rename \
  --enable-tar --enable-tar-gz \
  --hidden --dirs-first --readme \
  --header "Cache-Control: no-cache" \
  --tls-cert /etc/miniserve/tls.crt --tls-key /etc/miniserve/tls.key \
  --log-color never --title Files \
  -p 8443 /srv/share

要点：认证走 --auth-file 便于免重启换密码；上传限定 /upload 子目录并固定权限位；归档只开 tar/tar.gz 规避 zip 内存风险；TLS 直挂或改由前置网关终结；--log-color never 保证 journald 日志干净。

八、常见问题（FAQ）

Q1：--pastebin/-U/-m 启动报 required arguments 错误？ 它们依赖 --upload-files。实测报错原文：error: the following required arguments were not provided: --upload-files [<ALLOWED_UPLOAD_DIR>]，按 Usage 提示补齐即可。

Q2：--temp-directory 报 invalid value？ 目录必须预先存在：mkdir -p /var/tmp/miniserve-upload。官方 help 亦建议放磁盘而非内存文件系统（tmpfs 会让大文件上传占内存交换区）。

Q3：环境变量 MINISERVE_TEMP_UPLOAD_DIRECTORY 不生效？ 拼写问题——正确的名字是 MINISERVER_TEMP_UPLOAD_DIRECTORY（多 ER），0.35.0 --help 实查如此。

Q4：开了 -m image 为什么 curl 还能传 txt？ -m 的媒体类型提示主要下发给浏览器文件选择器（accept），0.35.0 服务端对 multipart 直传未强制校验（实测 303 且落盘）。需要严格白名单请在网关层做，或只对可信人群开放上传。

Q5：zip 下载大目录失败/进程内存飙升？ 官方警告 zip 是内存生成。改用 -r/-g（tar/tar.gz 流式），或对超大目录直接走 rsync 等专用同步工具。

Q6：多个 --auth 参数可以叠加吗？ 可以，重复传参即多用户；或统一收敛到 --auth-file。

九、参考链接

• 官方 README（Usage/Features 节与 0.35.0 一致）：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 常用 CLI 命令与工具详解》