很多内部文档工具最后都会卡在“开发机能看，换台机器就缺文件”：Markdown 散在项目文件夹里，CSS 和插图又对应了好几个零散的相对路径。Go 的 embed.FS 可以把这些资源全部编进二进制，再用 net/http 起一个本地预览服务，交付时只带一个可执行文件就够了。

最小可行做法是：用 //go:embed 收集 site/ 下的页面资源，通过 fs.Sub 去掉目录前缀，再交给 http.FileServer；构建后放到临时目录启动并用 curl 验收，才能确认它真的离线可用。

先把项目边界定成一个能验收的小工具

这个示例不做完整的 Markdown 编辑器，只解决一个很实用的交付问题：仓库里的 site/index.html、site/style.css 和插图被编译进 mdpreview，运行后在 127.0.0.1:8080 打开预览页。

目录保持简单，后面排查路径时不容易迷路：

mdpreview/
├── main.go
└── site/
    ├── index.html
    └── style.css

这里的验收标准也先写清楚：没有外部网络时首页能返回 200，页面引用的 CSS 也能返回 200，访问随机路径返回 404，而不是把错误页面误当成首页。

用 embed.FS 把 Markdown 预览页编进二进制

先把已经生成好的 Markdown 转成的 HTML 放进 site/index.html。embed 的路径相对于当前 Go 源文件，匹配范围不能越过所在目录，因此把资源放在同级 site/ 最省事。

package main

import (
    "embed"
    "io/fs"
    "log"
    "net/http"
)

//go:embed site/*
var embedded embed.FS

func main() {
    siteFS, err := fs.Sub(embedded, "site")
    if err != nil {
        log.Fatal(err)
    }

    handler := http.FileServer(http.FS(siteFS))
    log.Println("markdown preview: http://127.0.0.1:8080")
    if err := http.ListenAndServe("127.0.0.1:8080", handler); err != nil {
        log.Fatal(err)
    }
}

fs.Sub 是这里最容易漏掉的一步。没有它，文件服务器看到的是 site/index.html；有了它，浏览器请求 / 时才会在嵌入文件系统的根目录找到 index.html。这不是把文件复制到磁盘，而是在程序启动时读取二进制里的只读文件树。

site/index.html 只保留可验证的静态引用

  
LOCAL PREVIEW
    
今天的发布说明
    
页面、样式和图片都来自同一个 Go 二进制。
  

路径统一写成以 / 开头的站点根路径。这样页面从 / 打开，或者以后挂到子路由下，都不会因为当前 URL 层级变化而丢掉样式。

把嵌入文件安全地交给 HTTP

http.FileServer 已经处理了目录索引、文件读取和不存在路径的兜底逻辑。小工具不需要先把资源解压到临时目录，也不要自己拼接用户输入去访问本地磁盘。

如果只想允许预览首页和 CSS，可以再包一层轻量路由，把公开范围锁在两个资源上：

func onlyPreview(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        switch r.URL.Path {
        case "/", "/index.html", "/style.css":
            next.ServeHTTP(w, r)
        default:
            http.NotFound(w, r)
        }
    })
}

再把启动处改成 http.ListenAndServe("127.0.0.1:8080", onlyPreview(handler)) 即可。绑定回环地址是本地预览的一个小但重要的边界：它不会主动把文档服务暴露到局域网。要给同事访问时，再明确改成监听指定网卡，并补上鉴权。

构建后从临时目录验证真正的单文件交付

不要在项目目录里直接运行来证明离线交付成功，那样即使嵌入失败，当前目录里的 site/ 也可能让问题看起来正常。用构建产物加临时目录做一次检查：

go build -o mdpreview .
tmpdir=$(mktemp -d)
cp mdpreview "$tmpdir/"
cd "$tmpdir"
./mdpreview > preview.log 2>&1 &
server_pid=$!
trap 'kill "$server_pid"' EXIT

curl -fsS -o index.html -w '%{http_code}\n' http://127.0.0.1:8080/
curl -fsS -o style.css -w '%{http_code}\n' http://127.0.0.1:8080/style.css
curl -sS -o missing.txt -w '%{http_code}\n' http://127.0.0.1:8080/missing.css

预期输出是 200、200、404。若首页是 404，优先检查 fs.Sub 的目录名和 //go:embed site/* 的相对位置；若首页成功但样式丢失，检查 HTML 的引用路径和资源是否真的放在 site/ 下。

几个容易把离线预览做坏的细节

• 把动态文件写回 embed.FS：embed.FS 是只读的。预览内容需要实时编辑时，应把渲染结果放在内存或另一个可写目录。
• 嵌入隐藏文件却没检查构建上下文：通配符只匹配构建时可见的文件，先用 go list 或构建日志确认资源确实被打包。
• 直接监听所有网卡：本地文档不应默认暴露给同一网络的其他设备。
• 只用浏览器手工确认：至少把 200、200、404 三个请求写成脚本，后续改目录结构时才有回归保护。

相关问题

embed.FS 能直接渲染 Markdown 吗？

不能。它只负责嵌入和读取文件。可以在构建阶段把 Markdown 转成 HTML，也可以运行时用 Markdown 解析库把嵌入的 .md 读出来再渲染。

为什么要用 fs.Sub，而不是把 URL 写成 /site/？

两种方式都能工作，但 fs.Sub 可以把资源目录映射为站点根，更符合浏览器中的根路径引用，也能避免把项目内部目录名暴露给 URL。

单二进制适合做生产文档站吗？

适合小型内部文档、发布说明和离线演示；如果需要多人编辑、全文检索、权限和频繁更新，仍应使用专门的文档服务或外部存储。

验收结果应该落在三个状态上

这个小工具的价值不在代码量，而在交付边界清楚：构建时把 site/ 固定进二进制，服务端只暴露本地预览资源，验收脚本同时覆盖成功和失败路径。以后要接 Markdown 热更新、目录导航或搜索，也可以沿着“资源来源—渲染方式—HTTP 暴露范围”这三条线逐步扩展，而不用先推翻单文件启动方式。