miniserve实战：一条命令搭建局域网文件服务器，从共享上传到认证全跑通

/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}

临时给同事传一个 2GB 的安装包、把下载好的电影推到电视上、给团队挂一个资料目录让全组自取——这类需求几乎每个人都遇到过。用 Nginx 要写配置，用 Python 的 http.server 又缺上传、缺认证、还经常 MIME 类型出错。

本文详解开源工具 miniserve（GitHub 8100+ 星标，MIT 协议，Rust 编写）：从安装、目录共享、二维码访问，到上传、认证、TLS 加密、SPA 托管、WebDAV 与 systemd 常驻部署，所有命令均可直接复制运行，写作时基于当前最新版 v0.35.0 实测。无论你是想在局域网里快速传文件的普通用户，还是想挂一个常驻文件服务的开发者，都能在 5 分钟内上手。

一、miniserve 是什么：为什么不用 Python 和 Nginx

miniserve 的定位非常纯粹：一个单文件、零依赖、开箱即用的 HTTP 文件服务器。Windows 版可执行文件实测仅约 2.1MB，下载后双击即用，不写一行配置。

同样是“把目录挂到 HTTP 上”，三种常见方案的对比：

除此之外它还有几个加分项：文件夹压缩下载、扫码访问、多套主题、README.md 渲染、Range 断点续传、健康检查路由等。用官方的话说：“当你现在、立刻、马上就想通过 HTTP 分享一些文件的时候”，就是它的主场。

二、安装：Windows / Linux / macOS / Docker 一张表

Windows 用户没有 scoop 也没关系，直接去 GitHub Releases 下载那个 2MB 的 exe 即可。这就是单文件工具的最大好处：拷进 U 盘就等于随身带了一个文件服务器。

Docker 一条命令把宿主机的 /tmp 挂进去：

docker run -v /tmp:/tmp -p 8080:8080 –rm -it svenstaro/miniserve /tmp

装完在终端敲 miniserve –version，能看到 miniserve 0.35.0 就说明就绪了。

三、30 秒上手：目录共享与扫码访问

最基础的用法就一行命令：

# 共享一个目录（默认端口 8080）
miniserve ./项目资料

# 共享单个文件，对方打开即下载
miniserve ubuntu-24.04.iso

# 换端口、改标题、开启二维码
miniserve -p 9000 -q -t "项目资料共享" ./项目资料

启动后终端会打印访问地址，局域网内任何设备用浏览器打开 http://你的IP:端口 就能看到文件列表，支持按名称/大小/时间排序、搜索，中英文文件名均正常显示。

加了 -q 之后，网页右上角会出现 QR code 按钮，点开就是当前地址的二维码，手机扫码直接访问，不用对着手输 IP。实测界面如下，文件列表、大小、修改时间一目了然：

再给两个小技巧：

• –random-route 会生成一个随机 6 位路径（如 http://192.168.1.5/c789b6），避免链接被同网段无关人员随手猜到；
• -i 192.168.1.5 可以指定只绑某张网卡，写多个 -i 可同时绑多个地址。

四、开启上传：网页收文件比 IM 还快

加 -u 允许网页上传，-U 允许新建目录：

# 网页可上传、可建目录
miniserve -u -U -t "文件收集" ./收集箱

# 只收图片：部分手机浏览器会直接调起相机，拍完即传
miniserve -u -m image -q ./照片收集

# 重名文件自动改名（file.txt 变 file-1.txt），而不是报错
miniserve -u -o rename ./收集箱

界面上方会出现上传与建目录两个面板，把文件拖进窗口任意位置即可上传：

命令行党也可以用 curl 直接推文件：

# 先启动：miniserve -u — .
curl -F "path=@报告.pdf" "http://127.0.0.1:8080/upload?path=/"

注意这里有一个必踩的坑：-u 本身可以接路径参数（限定只允许传到哪个目录），所以“允许上传 + 指定共享目录”组合时必须用 — 把它们隔开，写成 miniserve -u — .；也正因为如此，-uv 这种合并短选项的写法在带 -u 时是无效的，要分开写成 -u -v。

五、认证与安全：明文密码、哈希密码、TLS 一个不少

共享不等于裸奔，miniserve 的安全配置相当齐全：

# 1. 明文账号密码
miniserve –auth joe:123 ./私密资料

# 2. SHA256 哈希密码，避免明文进 shell 历史
pw=$(echo -n "123" | sha256sum | cut -f 1 -d ' ')
miniserve –auth "joe:sha256:$pw" ./私密资料

# 3. 多账号写进文件，一行一个（三种格式可混用）
miniserve –auth-file auth.txt ./私密资料

# 4. 开启 TLS，配 fullchain 证书时还能加 HSTS 响应头
miniserve –tls-cert fullchain.pem –tls-key my.key ./私密资料

auth.txt 的内容长这样：

joe:123
bob:sha256:a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3
bill:

再配合几个默认就帮你做对的安全项：隐藏文件默认不显示（要 -H 才显示）、符号链接默认跟随（不放心可加 -P 禁用并隐藏）、-I 可以彻底关闭目录索引、只允许精确路径访问。公网机器上部署时，建议认证、TLS、-i 绑内网网卡三件套齐上。

六、进阶玩法：打包下载、README 渲染、SPA 托管与 WebDAV

这一节是 miniserve 超出“传文件”预期的部分：

# 允许网页一键打包下载整个目录（tar / tar.gz / zip 三种格式）
miniserve -r -g -z ./素材库

# 目录里放个 README.md，像 GitHub 一样渲染成说明页
miniserve –readme ./项目资料

# 托管前端打包产物：404 全部回落到 index.html，交给前端路由处理
miniserve –spa –index index.html ./dist

# 只读 WebDAV：Windows 资源管理器可映射成网络驱动器
miniserve –enable-webdav ./共享盘

# 页脚显示 wget 命令，对方复制即可整目录递归拉取
miniserve -W ./数据集

下面这张图是用 monokai 暗色主题（-d monokai，亮色用 -c，另有 archlinux、zenburn、squirrel 三种配色）加 –readme 和 -W 跑起来的效果：目录列表下方是渲染好的 README，页脚是给对方的 wget 命令，暗色模式还会跟随系统设置自动切换：

另外两个冷门但好用的开关：–header "Cache-Control:no-cache" 可以插入自定义响应头，已存在的头不会被覆盖；请求加 ?raw=true 参数则输出极简 HTML，lynx、w3m 这类终端浏览器也能正常浏览。

七、systemd 常驻：挂机当家用文件中枢

临时共享一条命令就够，但要 7×24 挂着，就交给 systemd。仓库自带一个加固过的模板单元文件：

# 安装模板单元
sudo cp packaging/miniserve@.service /etc/systemd/system/

# 路径要用 systemd-escape 转义：/home/user/share 对应 -home-user-share
sudo systemctl enable –now miniserve@-home-user-share

想自定义启动参数，用 systemctl edit miniserve@-home-user-share 写一个 override.conf：

[Service]
ExecStart=
ExecStart=/usr/bin/miniserve –enable-tar –enable-zip –no-symlinks –verbose -i ::1 -p 1234 –title hello — %I

不想改单元文件也可以走环境变量：MINISERVE_PORT、MINISERVE_AUTH、MINISERVE_TITLE 等几乎所有参数都有对应变量，写进 [Service] 段的 Environment= 即可。注意如果服务要直接暴露在公网网卡上，可能还需要按模板注释调整 IPAddressAllow / IPAddressDeny。

八、避坑清单：7 个高频问题

1. -u 后面写的目录怎么变成上传目标了？
-u 的可选参数是“允许上传的目标目录”（相对共享根目录），不是共享目录本身。两者都要时用 — 分隔：miniserve -u — ./共享目录。

2. zip 打包大目录时报内存不足？
zip 是在内存里生成的，官方明确警告大目录可能 OOM。大文件目录用 -g（tar.gz）代替 -z。

3. 局域网其他设备访问不了？
九成是防火墙没放行端口。Windows 第一次运行会弹防火墙授权，选“允许”；Linux 放行对应端口即可。另外确认没有用 -i 把自己绑到了 127.0.0.1。

4. 上传重名文件直接报错？
默认策略就是报错（-o error），改成 -o rename 自动加序号，或 -o overwrite 直接覆盖。

5. 想让别人只能下载指定文件、不能浏览目录列表？
加 -I 关闭索引，再把链接精确到文件路径。

6. 中文文件名会乱码吗？
实测 v0.35.0 的网页列表、下载、打包均正常，无需任何配置。

7. 端口 8080 被占了？
-p 9000 换一个，或设环境变量 MINISERVE_PORT=9000。

九、总结

• miniserve 是 Rust 编写的单文件 HTTP 文件服务器，Windows 版仅约 2MB，零配置一条命令起服务；
• 共享：目录/单文件、排序与搜索、二维码扫码访问、随机路径防猜测；
• 写入：网页拖拽上传、curl 上传、建目录、重名自动改名，手机端可直调相机；
• 安全：明文/哈希/文件多账号认证、TLS、网卡绑定、隐藏文件与符号链接默认安全；
• 进阶：tar.gz/zip 打包下载、README 渲染、SPA 静态托管、只读 WebDAV、systemd 加固模板；
• 定位清晰：临时共享选它，常驻轻量文件服务也选它；要复杂权限和反代，再上 Nginx。

如果你也常在局域网里传文件，建议把那个 2MB 的 exe 丢进 U 盘常备一个。评论区聊聊你的文件共享方案，是 python -m http.server 党还是 scp 党？

参考资料

• miniserve GitHub 仓库（svenstaro/miniserve）
• miniserve Releases 下载页

相关链接