GoSPA 完整快速上手教程

下面给你一份完整、可直接照着操作的 GoSPA 快速上手教程，从安装到部署全流程，一步一步跟着做就能跑起来。

---

GoSPA 完整快速上手教程

0. 环境要求

• Go 1.22+
• 基础 Go 开发环境（已配置 GOPATH/GOROOT）
• 可选：air（热重载工具）

1. 安装 GoSPA CLI

打开终端执行：

go install github.com/halvves/gospa/cmd/gospa@latest

安装完成后，检查是否可用：

gospa version

2. 创建新项目

gospa new my-gospa-app
cd my-gospa-app

GoSPA 会自动生成：

• 项目结构（文件路由）
• Templ 模板支持
• 基础布局与示例页面
• 内置开发服务器

3. 目录结构（核心）

/pages
  index.gospa    # 首页 /
  about.gospa    # 关于页 /about
/layouts
  main.gospa     # 全局布局
/assets
  css、js 等静态资源
gospa.config.go  # 配置文件

路由规则：

• /pages/index.gospa → /
• /pages/user/[id].gospa → /user/123
• 嵌套目录自动生成嵌套路由

4. 启动开发服务

gospa dev

默认运行在：

http://localhost:3000

特点：

• 热重载：修改 .gospa 文件自动刷新浏览器
• 实时编译 Templ
• 内置 WebSocket 状态同步

5. 编写第一个页面（index.gospa）

<script lang="go">
var count = $state(0)

func increment() {
	count++
}
</script>

<main>
	<h1>Hello GoSPA</h1>
	<p>Count: { count }</p>
	<button on:click={increment}>+1</button>
</main>

保存后浏览器会自动更新，无需刷新。

6. 路由与页面跳转

新建 /pages/about.gospa：

<script lang="go"></script>

<h1>About</h1>
<p>This is GoSPA</p>
<a href="/">Back home</a>

访问：

http://localhost:3000/about

7. 使用布局（layouts/main.gospa）

布局文件用于统一导航、页头、页脚：

<script lang="go"></script>

<nav>
	<a href="/">Home</a>
	<a href="/about">About</a>
</nav>

<!-- 子页面内容插入这里 -->
{children}

<footer>Powered by GoSPA</footer>

所有页面会自动套用这个布局。

8. 调用后端函数（Remote Action）

GoSPA 支持前端直接调用 Go 后端函数：

<script lang="go">
import "time"

// 后端函数
func ServerTime() string {
	return time.Now().Format(time.RFC3339)
}
</script>

<p>Server time: { ServerTime() }</p>

无需写 API、无需序列化，直接调用。

9. 构建生产版本

gospa build

生成：

• 单个二进制文件
• 内置所有静态资源
• 无外部依赖

10. 部署运行

直接运行构建后的文件：

./my-gospa-app

可部署到：

• Render（你给的网址就是这种）
• Vercel
• 任何 Linux 服务器
• Docker 容器