go:embed：零构建前端打进单二进制

本文是《从 0 写 Agent》系列第 38 章。这个系列基于开源项目 agents-go（OpenAI Agents SDK 的 Go 移植版），用 Go 从零实现一个生产级 Agent 运行时；本章讲「go:embed + 零构建前端」。

agents-server 是单二进制，后端 Go + 前端 React，全在一个文件里。前端怎么进二进制的？不用 webpack、不用 vite，用 go:embed + importmap + ESM CDN。

这一章拆这个"野路子但有效"的前端架构，以及它为什么能让部署变得极致简单。

go:embed：9 行代码打进前端

agents-server 的前端嵌入极其简单（web/embed.go）：

// internal/web/embed.go（完整文件就 9 行）
package web

import "embed"

//go:embed static/*
var StaticFS embed.FS

//go:embed static/* 把整个 static/ 目录编译期嵌进二进制。 embed.FS 是个虚拟文件系统，运行时能像读真文件一样读里面的资源。

服务端怎么用

// cmd/root.go:198
staticFS, _ := fs.Sub(web.StaticFS, "static")  // 剥掉 "static/" 前缀
srv.ServeStatic(staticFS)

// server.go:64（概念）
func (s *Server) ServeStatic(fsys fs.FS) {
    r.NoRoute(func(c *gin.Context) {
        // 尝试开文件
        f, err := fsys.Open(c.Request.URL.Path)
        if err != nil {
            // 打不开 → 回退到 index.html（SPA fallback）
            c.FileFromFS("index.html", http.FS(fsys))
            return
        }
        c.FileFromFS(c.Request.URL.Path, http.FS(fsys))
    })
}

NoRoute 兜底，任何不匹配 API 路由的请求，先尝试开静态文件，打不开就回退 index.html。这是 SPA history-mode fallback，前端路由（如 /agents/123）刷新时不会 404。

零构建前端：importmap + ESM CDN

这是 agents-server 前端最"野"的地方。不用任何构建工具，直接在浏览器里跑 JSX：

<!-- index.html（概念） -->
<script type="importmap">
{
  "imports": {
    "react": "https://esm.sh/react@19",
    "react-dom/client": "https://esm.sh/react-dom@19/client",
    "marked": "https://esm.sh/marked",
    "highlight.js": "https://esm.sh/highlight.js"
  }
}
</script>
<script type="module" src="/app.jsx"></script>

importmap，告诉浏览器"react 这个 import 对应 esm.sh 上的 URL"。浏览器原生 ESM 会从 CDN 加载 React。

/app.jsx，直接加载 JSX 文件。浏览器原生不认 JSX，但服务端特意注册了 MIME 类型：

// server.go:15
func init() {
    mime.AddExtensionType(".jsx", "application/javascript")
}

加上 esm.sh 的自动 transform（或内联 babel），JSX 在浏览器里直接跑。

为什么这么"野"

作者自己在帖子里自嘲："没有构建步骤，裸 JSX 通过 go:embed 打进二进制，浏览器端 ESM 直接跑，React.createElement 手搓 UI，不要学这个写法哈，纯粹是为了保持单二进制部署才这么搞的。"

为什么"不要学"？ 因为这种写法有代价，

• 没有打包优化（tree-shaking、压缩）
• 每次加载要从 CDN 拉 React（首次慢）
• JSX 运行时转换有开销
• 不能用需要构建的生态（TypeScript、CSS Modules）

但它的价值极其明确，单二进制。 不用 npm install、不用 npm run build、不用 node_modules。编译 Go 二进制时前端自动进去。部署体验是降维打击。

设计权衡：零构建 vs 标准构建

agents-server 选零构建，是为了"单二进制"这个核心价值。 如果你做大型产品，还是用标准构建。这是"部署体验 vs 工程规范"的权衡，作者清醒地选择了前者（并自嘲了）。

PWA 支持

agents-server 的前端还是个 PWA：

<!-- index.html -->
<link rel="manifest" href="/manifest.json">
<script src="/sw.js"></script>  <!-- Service Worker -->

Service Worker 做离线缓存，CDN 资源缓存后，断网也能用。这对"本地部署 + 偶尔断网"的场景友好。

小结

读完这一章，你应该理解：

1. go:embed，//go:embed static/* 把前端打进二进制，9 行代码
2. SPA fallback，NoRoute 兜底，前端路由刷新不 404
3. 零构建，importmap + ESM CDN + 运行时 JSX，不用 webpack
4. 为什么"野"，单二进制的代价是放弃构建优化，作者自嘲但选择
5. PWA，Service Worker 离线缓存

go:embed + 零构建 = 极致的单二进制部署。 这是 agents-server "下载一个文件就能跑"的秘诀。

下一篇

第 39 章，ChatGPT OAuth：用订阅额度跑 Agent。agents-server 支持用 ChatGPT 订阅账号跑 Agent（不烧 API 费）。这靠 OAuth 2.1 + PKCE + 本地回调服务器 + postMessage 弹窗通信。Part VI 的最后一章。

本文是《从 0 写 Agent》系列第 38 章，案例代码基于开源项目 agents-go（OpenAI Agents SDK 的 Go 移植版）。全系列目录见总览。