embed.fs路径必须是编译时静态确定的相对路径，仅限当前包或其子目录，不支持../、绝对路径或运行时拼接；需确保文件真实存在、大小写严格匹配，并用fs.readdir调试验证嵌入结构。
embed.FS 路径必须是编译时静态确定的相对路径
不是运行时拼出来的、也不能带 ../ 或绝对路径——Go 编译器在 build 阶段就解析 //go:embed，路径必须指向当前包目录或其子目录下真实存在的文件。写成 //go:embed assets/logo.png 没问题，但 //go:embed ../../config.yaml 或 //go:embed /tmp/data.json 会直接报 pattern matches no files。
常见错误现象：本地能跑，CI 构建失败；或者 fs.ReadFile(fsys, "assets/logo.png") 返回 no such file or directory，但文件明明在磁盘上。
- 确保资源（如
dist/、static/）放在与.go文件同一级或子目录下，比如cmd/server/dist/ -
//go:embed必须紧贴变量声明，中间不能有空行或注释 - 调试时先用
fs.ReadDir(fsys, ".")打印顶层结构，确认嵌入是否生效 - 通配符只支持一级，如
dist/*可以，dist/**不行
前端构建产物必须先生成再 embed，不能直读 node_modules
embed.FS 无法处理 node_modules：它体积大、含符号链接、二进制文件和动态生成内容，Go 编译器设计上就跳过这类目录——这不是权限或配置问题，是根本不可行。
正确路径只有一条：前端项目（Vue/React）先执行构建命令，产出纯静态文件到 dist/ 或 build/，再把这个目录整体 embed。
Colly 是一个用于 Go 语言的快速开源爬取和爬虫框架。它适用于从简单的页面提取到异步爬虫处理大量页面集合，支持请求回调和结构化解析。
- Vue 项目：运行
npm run build，确认输出在dist/目录 - React 项目：默认
npm run build输出到build/，可改homepage字段控制资源路径前缀 - 构建前清空目标目录，避免旧 JS/CSS 被意外 embed 进去
- 检查构建后所有资源（HTML、JS、CSS、图片）是否都在扁平目录下，嵌套过深会导致
http.FileServer匹配失败
SPA 路由刷新 404？别直接用 http.FileServer
把 embed.FS 直接传给 http.FileServer(http.FS(fsys))，访问 /user/profile 就会 404——因为 Go 服务器不知道这是前端路由，它只找物理文件。
必须自己实现 fallback：先查文件是否存在，不存在就返回 index.html，让前端路由接管。
- 不要用
http.StripPrefix+http.FileServer组合，它不 fallback - 推荐用
fs.Open()显式判断：f, err := fsys.Open(path)，err != nil时调用http.ServeFile(w, r, "dist/index.html") - 手动设置
Content-Type: text/html; charset=utf-8，否则某些浏览器可能乱码或拒绝渲染 - 用
fs.Sub(fsys, "dist")切出子树，避免路径越界（比如请求/../etc/passwd）
template.ParseFS 使用时变量名和 glob 模式要严格匹配
template.ParseFS 确实支持 embed.FS，但常见失败不是接口不兼容，而是参数写错。
典型错误：写成 template.ParseFS(embededFS, "*.html") 却忘了 embededFS 是变量名，不是类型；或漏了 import _ "embed" 导致编译失败。
- glob 模式必须能匹配到嵌入路径中的实际文件名，比如
templates/*.tmpl对应templates/login.tmpl - 路径区分大小写，
Templates/和templates/是两个不同目录 - 模板中引用静态资源（如
<link href="/css/app.css">）时，确保该 CSS 真实存在于 embed 的路径中，且路径大小写一致 - 若用 Gin/Echo 等框架，注意它们的静态服务封装可能掩盖底层路径问题，建议先用
net/http原生 handler 验证 embed 结构
golang免费学习笔记（深入）：立即使用
在学习笔记中，你将探索golang的核心概念和高级技巧！
