Go WebAssembly 怎么读写 localStorage：syscall/js 的边界、异常与加载检查

把一段 Go 逻辑放进浏览器后，最容易卡住的往往不是编译，而是第一次碰到浏览器对象：设置页想记住主题色，代码里却没有 window.localStorage。在 GOOS=js GOARCH=wasm 目标下，syscall/js 能跨过这层边界；不过存储被隐私策略禁用、值不是合法 JSON、Wasm 启动脚本跟编译器不匹配，都会让一个看似很小的功能变得难查。

在 Go WebAssembly 场景下读写 localStorage，核心是通过 syscall/js 层做浏览器对象互操作，优先对齐构建目标和配套加载脚本，把 JS 相关的边界调用集中封装成少数统一接口，提前兼容存储禁用、值格式异常等边缘场景，不要把敏感数据放在 localStorage 中存储。

浏览器里的 Go Wasm 能做什么，不能做什么

syscall/js 是 Go 的浏览器互操作层。它给出的不是一套重新包装过的 Web API，而是一组接近 JavaScript 语义的值操作：从 js.Global() 取全局对象，用 Get 读取属性，用 Call 调方法。因此 localStorage 的调用路径很直白：js.Global().Get("localStorage")，再调用 getItem 或 setItem。

这里先别急着把所有前端状态都塞进去。localStorage 是浏览器页面的同步存储，适合主题、列表筛选项、最近一次输入这类小而可丢的状态；它不负责跨设备同步，也不该保存访问令牌、密码或可识别用户的隐私数据。无痕模式、嵌入式页面、用户的站点数据限制，都可能让读取或写入失败。

先把构建与加载链路对齐

最小工程只要有一个 main 包。构建完成后，浏览器还需要 Go 运行时附带的加载脚本。常见故障是仓库里留着很久以前复制的启动脚本：页面能请求到 main.wasm，运行时却在初始化阶段报出难以对应的错误。把脚本和构建动作放在同一个发布步骤里，比人工记版本可靠得多。

# 生成浏览器可运行的 Wasm 模块
GOOS=js GOARCH=wasm go build -o public/main.wasm ./cmd/web

# 从当前 Go 工具链同步运行时加载脚本，并统一部署名
cp "$(go env GOROOT)/lib/wasm/wasm_"*.js public/wasm_runtime.js

页面加载时要注意两件小事。第一，main.wasm 应由 HTTP 服务返回，并带正确的 application/wasm 内容类型；否则 WebAssembly.instantiateStreaming 可能直接拒绝。第二，go.run 会进入 Go 运行时，浏览器侧的初始化代码不要假设它会同步返回。

用一个窄封装读写 localStorage

业务代码到处出现 js.Global().Get(...).Call(...)，后面很难区分“没有这个键”“JSON 已损坏”和“浏览器抛了异常”。更稳的做法是把 JavaScript 调用收在一个文件里，业务层只拿 Go 结构体和 error。下面的示例保存一个主题设置；protectJS 把 JavaScript 抛出的异常变成普通错误，调用方不会因为隐私策略或配额问题把整个 Wasm 运行时打断。

package main

import (
	"encoding/json"
	"errors"
	"fmt"
	"syscall/js"
)

type Settings struct {
	Theme string `json:"theme"`
}

func protectJS(fn func()) (err error) {
	defer func() {
		if v := recover(); v != nil {
			err = fmt.Errorf("browser storage call failed: %v", v)
		}
	}()
	fn()
	return nil
}

func storage() (js.Value, error) {
	v := js.Global().Get("localStorage")
	if v.Type() == js.TypeUndefined || v.Type() == js.TypeNull {
		return js.Undefined(), errors.New("localStorage unavailable")
	}
	return v, nil
}

func saveSettings(in Settings) error {
	b, err := json.Marshal(in)
	if err != nil {
		return fmt.Errorf("encode settings: %w", err)
	}
	s, err := storage()
	if err != nil {
		return err
	}
	return protectJS(func() { s.Call("setItem", "ui.settings", string(b)) })
}

func loadSettings() (Settings, error) {
	var out Settings
	s, err := storage()
	if err != nil {
		return out, err
	}
	var raw string
	if err := protectJS(func() { raw = s.Call("getItem", "ui.settings").String() }); err != nil {
		return out, err
	}
	if raw == "" || raw == "" {
		return out, errors.New("ui.settings not found")
	}
	if err := json.Unmarshal([]byte(raw), &out); err != nil {
		return out, fmt.Errorf("decode ui.settings: %w", err)
	}
	return out, nil
}

上面有一个容易被忽略的细节：JavaScript 的 null 不是 Go 的空字符串。为了避免把不存在的键误当成内容，生产代码更建议直接把 getItem 的返回值保存成 js.Value，先判断它是否为 js.TypeNull，再调用 String。示例为了把错误路径压缩在一处才保留了字符串检查；真正项目里不要依赖 "" 这个表现。

把空值判断写成可复用版本

把上面的读取函数改成下面这样，语义会更明确：键不存在是一个业务结果，不是 JSON 错误。若页面希望首次打开采用默认主题，调用方只需对 found 为 false 的情况使用默认值。

func getString(key string) (value string, found bool, err error) {
	s, err := storage()
	if err != nil {
		return "", false, err
	}
	var v js.Value
	if err := protectJS(func() { v = s.Call("getItem", key) }); err != nil {
		return "", false, err
	}
	if v.Type() == js.TypeNull || v.Type() == js.TypeUndefined {
		return "", false, nil
	}
	return v.String(), true, nil
}

浏览器环境里的兼容与排错顺序

Wasm 本身和 localStorage 都不是“构建成功就一定能写入”的保证。排错时我更建议从最外层的网络和运行时开始：先在 Network 面板确认 main.wasm 返回 200 且响应类型合理，再看 Console 是否有加载器异常，最后才看 ui.settings 的值。这样不会把服务器返回了 HTML 错误页、浏览器禁止第三方存储、数据格式变更混在同一个问题里。

• 加载失败：确认 Wasm 启动脚本和当前编译器来自同一 Go 大版本，并检查 Wasm 文件不是 404 页面。
• 写入失败：检查页面是否处在受限的嵌入环境、用户是否禁止站点数据，以及是否超过可用配额。
• 读取失败：先保留原始字符串到调试日志，再判断 JSON 结构是不是已经换过字段；不要立即覆盖旧值。
• 页面卡顿：localStorage 是同步 API。大对象或高频写入应改为节流、延迟写入，或评估 IndexedDB。

别把 localStorage 当成通用数据库

它的优点是近、简单、无需额外请求；代价是作用域只在当前站点、容量和策略由浏览器控制，而且前端脚本能读到的内容也可能被页面中的恶意脚本读到。主题色、展开状态、草稿提示可以接受这个边界；登录凭据、支付信息、完整业务缓存不应该放在这里。若确实要保留用户设置，服务端同步或加密后存储也要先把威胁模型想清楚。

延伸问答

Go Wasm 能直接调用所有浏览器 API 吗？

只要目标是浏览器的 js/wasm 环境，通常可以经 syscall/js 访问全局对象和方法；但 API 是否存在仍取决于浏览器、权限策略和页面上下文。先判断对象类型，再调用方法。

为什么不能把 WASI 构建产物拿来访问 localStorage？

wasip1/wasm 面向 WASI 系统调用环境，不等于浏览器页面。它没有 window、DOM 或 localStorage；需要浏览器 API 时应选择 js/wasm。

localStorage 里的 JSON 损坏了怎么办？

不要在解码失败后马上覆盖。先记录键名和原始长度，保留现场用于判断版本迁移还是手工修改；确认无须恢复后，再删除该键并回落到默认值。

Wasm 文件很大时只靠 localStorage 能优化加载吗？

不能。localStorage 只适合保存少量界面状态。Wasm 体积要从构建产物、静态资源压缩、缓存头和按需加载处理，别用浏览器同步存储承载模块内容。

把 Go 代码放进浏览器，真正需要维护的是边界：构建目标和运行时脚本要配套，JavaScript 调用要集中，浏览器存储失败要被当成正常分支，敏感数据则留在它该在的位置。这样即使页面从一个主题开关扩展到更复杂的设置面板，排查路径也不会散掉。