当前位置：首页 > news >正文

LobeChat结合GitHub Pages发布静态AI页面

news 2026/5/12 16:38:03

LobeChat 结合 GitHub Pages：打造零成本静态 AI 聊天门户

在个人开发者和开源项目快速崛起的今天，越来越多的技术爱好者希望将大语言模型（LLM）的能力以直观、可交互的方式展示出来。然而，部署一个完整的 AI 对话系统往往意味着要搭建后端服务、管理 API 密钥、处理安全策略，甚至还要支付不菲的云服务器费用——这对许多轻量级需求来说显然“杀鸡用牛刀”。

有没有一种方式，既能拥有类 ChatGPT 的交互体验，又能做到免运维、零成本、一键发布？答案是肯定的：LobeChat + GitHub Pages的组合正在成为这一需求下的理想实践路径。

LobeChat 并不是一个大模型本身，而是一个现代化的开源聊天界面框架，基于 Next.js 构建，支持接入 OpenAI、Ollama、Hugging Face、Azure 等多种模型后端。它提供了角色预设、插件扩展、文件上传、语音输入等完整功能，开箱即用，极大降低了开发门槛。

更关键的是，LobeChat 支持通过next export生成完全静态的 HTML 页面。这意味着你可以把它像博客一样托管在 GitHub Pages 上——无需服务器、无需运行时、无需支付任何费用，只需一次配置，就能让全世界通过 URL 访问你的专属 AI 助手。

但这背后也藏着几个值得深思的问题：
- 静态页面如何调用需要认证的模型 API？
- 客户端暴露密钥会不会带来安全风险？
- 如何保证跨域请求能正常工作？
- 是否真的适合生产环境？

我们不妨从实际出发，一步步拆解这个看似“不可能”的技术方案是如何落地的。

当你运行npm run build && npm run export时，Next.js 会将整个应用编译为静态资源输出到out目录。这要求项目必须使用静态生成（SSG），不能依赖服务端渲染（SSR）或动态 API 路由。幸运的是，LobeChat 的前端逻辑本就以客户端为主，所有模型通信都发生在浏览器中，因此天然适配这种模式。

为了适配 GitHub Pages 的子路径部署（例如https://username.github.io/chat-bot），还需要在next.config.js中设置basePath：

const nextConfig = { output: 'export', basePath: '/chat-bot', // 必须与仓库名一致 images: { unoptimized: true, // 静态导出不支持 next/image 的动态优化 }, };

这里的unoptimized: true是必要的，因为next/image在静态模式下会尝试访问/_next/image这类动态路由，而在纯静态环境中这些路由并不存在，会导致 404 错误。关闭图像优化是最简单有效的解决方案。

至于环境变量，.env.local文件中的配置会在构建时被注入前端代码。比如你设置了：

OPENAI_API_KEY=sk-proj-xxxxxx DEFAULT_MODEL=gpt-3.5-turbo OLLAMA_PROXY_URL=http://localhost:11434

这些值最终都会被打包进 JavaScript 文件中。一旦部署到 GitHub Pages，任何人都可以通过查看网页源码或 DevTools 找到你的 OpenAI 密钥——这是该方案最常被质疑的安全短板。

所以问题来了：我们真的能在公开静态页面里放 API 密钥吗？

严格来说，不能。但我们可以换种思路来规避风险。

如果你的目标只是搭建一个本地可用的私人助手，那么可以这样设计架构：
前端部署在 GitHub Pages 上，但模型服务运行在你自己的电脑上（如 Ollama）。LobeChat 前端通过内网地址（如http://192.168.x.x:11434）或公网映射（如 via ngrok）连接本地模型。此时前端虽然公开，但它指向的是你私有的、受控的服务端点，API 不对外暴露，数据也不离开本地网络。

这种方式特别适合以下场景：
- 演示本地大模型能力
- 构建家庭知识库问答机器人
- 教学实验中的学生练习平台

即便别人拿到了页面链接，也无法调用你的模型，除非他们能访问你的局域网或隧道地址。本质上，这是一种“静态前端 + 私有后端”的设计哲学，既利用了 CDN 的高速分发优势，又保留了对核心资源的控制权。

当然，如果你想完全避免客户端调用带来的安全隐患，也可以引入一层轻量级代理。比如用 Vercel 或 Cloudflare Workers 搭建一个简单的转发函数，把/v1/chat/completions请求代理到 OpenAI，并在服务端注入密钥：

// 示例：Cloudflare Worker export default { async fetch(request, env) { const url = new URL(request.url); const target = 'https://api.openai.com' + url.pathname + url.search; const modifiedRequest = new Request(target, { method: request.method, headers: { ...request.headers, 'Authorization': `Bearer ${env.OPENAI_API_KEY}`, 'Content-Type': 'application/json', }, body: request.body, }); return fetch(modifiedRequest); } };

然后在 LobeChat 中将模型网关指向你的代理地址（如https://ai-proxy.example.workers.dev）。这样一来，前端不再持有密钥，安全性大幅提升，同时依然保持低成本和易维护性。

GitHub Pages 作为 GitHub 内建的静态托管服务，完美契合这类项目的发布需求。你只需要将构建好的out目录推送到gh-pages分支，或者启用主分支的/docs目录即可自动上线。更重要的是，它原生支持 HTTPS、全球 CDN 加速、自定义域名和 GitHub Actions 自动化部署。

下面是一个典型的 CI/CD 工作流配置：

name: Deploy LobeChat to GitHub Pages on: push: branches: [ main ] jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Setup Node.js uses: actions/setup-node@v4 with: node-version: '18' - name: Install dependencies run: npm install - name: Build static site run: | npm run build npm run export - name: Deploy to GitHub Pages uses: peaceiris/actions-gh-pages@v3 with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./out

每次提交代码后，GitHub Actions 会自动完成依赖安装、构建和部署全过程，几分钟后更新内容即可生效。整个流程无需人工干预，非常适合持续迭代的个人项目。

值得一提的是，GitHub Pages 虽然免费，但也有一些限制需要注意：
- 单仓库最大 1GB
- 单文件不超过 100MB
- 构建时间最长 10 分钟
- 流量虽无硬限，但禁止大规模爬取或滥用

对于 LobeChat 这类以文本交互为主的轻量应用，这些限制几乎不会构成瓶颈。即使加上一些静态资源和图标，总包体积通常也在几 MB 级别，加载迅速，用户体验良好。

从应用场景来看，这套组合拳尤其适合那些不需要高并发、强调快速验证和低成本试错的项目。比如：