5分钟跑通OpenFrame OSS Frontend:本地开发环境快速搭建与验证指南
5分钟跑通OpenFrame OSS Frontend:本地开发环境快速搭建与验证指南
OpenFrame OSS Frontend 是基于 Next.js(App Router)构建的开源 Web 前端,为 MSP(托管服务商)提供设备管理、工单系统、监控、脚本库和 AI 助手(Mingo AI)的一体化操作界面。本文是一份面向新手的本地开发环境搭建教程:只需 5 分钟,即可完成仓库克隆、依赖安装、环境变量配置,并通过 npm run dev 在 http://localhost:3000 跑通整个前端应用,最后用测试与类型检查完成环境验证。
环境准备:检查 Node.js 24 与 npm 版本
在开始之前,先确认本地工具链满足要求(详见 docs/getting-started/prerequisites.md):
| 工具 | 要求版本 | 约束位置 |
|---|---|---|
| Node.js | 24 |
仓库根目录 .nvmrc |
| npm | >=11.11.0 |
apps/web/package.json 的 devEngines.packageManager |
| Git | 任意近期版本 | — |
使用 nvm 可自动匹配 .nvmrc 中的版本:
nvm install
nvm use
node --version # 期望输出 v24.x
npm --version # 期望 >= 11.11.0
⚠️ 该仓库通过
devEngines强制要求 npm>=11.11.0,旧版本 npm 会在安装时直接报错而不是静默继续。
克隆仓库:了解 Monorepo 三大应用
git clone https://gitcode.com/gh_mirrors/op/openframe-oss-frontend
cd openframe-oss-frontend
这是一个 Monorepo,包含三个共享同一套前端代码的应用(布局说明见 README.md):
| 应用 | 路径 | 技术栈 | 说明 |
|---|---|---|---|
| Web(主应用) | apps/web |
Next.js + React + TypeScript | 日常开发的主战场 |
| 桌面壳 | apps/desktop |
Tauri(Rust) | 嵌入 Web 静态导出的桌面应用 |
| 移动壳 | apps/mobile |
Capacitor | 包装同一份导出的 iOS/Android 应用 |
桌面端与移动端不含独立 UI 代码,它们直接嵌入 Web 应用的静态导出,所以 90% 的日常开发都发生在 apps/web 目录。
安装依赖与配置环境变量
进入 Web 应用目录并安装依赖:
cd apps/web
npm ci
💡 官方推荐使用
npm ci而非npm install,它严格锁定 lockfile 版本,保证可复现的安装结果。
接下来复制示例环境文件并微调(变量说明见 apps/web/.env.example):
cp .env.example .env.local
关键变量一览:
| 变量 | 作用 | 默认值 |
|---|---|---|
NEXT_PUBLIC_APP_MODE |
部署模式:oss-tenant / saas-tenant / saas-shared |
oss-tenant |
NEXT_PUBLIC_AUTH_CHECK_INTERVAL |
认证状态轮询间隔(毫秒) | 60000 |
NEXT_PUBLIC_ENABLE_DEV_TICKET_OBSERVER |
启用 SSO 的 devTicket 自动检测 | false |
NEXT_PUBLIC_FEATURE_SCRIPT_SCHEDULE |
脚本调度功能开关 | false |
本地跑通前端时,保持默认的 NEXT_PUBLIC_APP_MODE=oss-tenant 即可——它让前端按自身源地址解析 API 调用,无需额外配置即可启动。
启动开发服务器:npm run dev 快速跑通应用
npm run dev
该命令实际执行 next dev -p ${PORT:-3000},终端出现如下输出即表示启动成功:
▲ Next.js 16
- Local: http://localhost:3000
✓ Ready in 1.2s
打开浏览器访问 http://localhost:3000,应能看到 OpenFrame 的登录页 / 应用外壳正常渲染。如需换端口:
PORT=4000 npm run dev
📌 在
oss-tenant模式下,前端期望由自身源地址提供后端 API(如/api/graphql)。若没有后端服务,界面外壳可正常显示,但依赖 API 的视图(设备列表、监控数据等)会处于加载或错误状态——这对纯前端 Quick Start 来说是预期行为,属于正常现象。
验证环境:测试、类型检查与 Lint 三连
跑通页面后,建议用三条命令确认环境完全健康:
npm run test # Vitest + Node 内置测试双跑
npm run type-check # tsc --noEmit 类型检查
npm run lint # ESLint(--max-warnings 0,零容忍)
预期结果对照表:
| 命令 | 成功标准 |
|---|---|
npm ci |
退出码 0,node_modules/ 正常生成 |
npm run dev |
终端输出 Ready 横幅,http://localhost:3000 可访问 |
npm run test |
所有测试文件通过 |
npm run type-check |
无 TypeScript 错误 |
npm run lint |
无 ESLint 错误/警告 |
如果 npm run dev 立即报模块解析错误,回到 apps/web 重新执行一次 npm ci 即可——不完整的安装是首次运行最常见的失败原因。
常见问题速查与下一步
- 安装被 npm 版本拦截:执行
npm install -g npm@latest升级到 11.11.0 以上。 - 端口被占用:用
PORT=4000 npm run dev换端口启动。 - 想本地联调共享 UI 库:仓库提供
npm run core:link/core:unlink(基于 yalc)将@flamingo-stack/openframe-frontend-core指向本地构建。 - 编辑 GraphQL 片段时:并行运行
npm run relay:watch保持 Relay 产物同步。
环境跑通之后,建议按以下路径继续深入:
- 快速上手引导:docs/getting-started/quick-start.md
- 环境变量详解与租户模式:docs/development/setup/environment.md
- 日常开发工作流(热更新、调试器配置):docs/development/setup/local-development.md
- 贡献规范:CONTRIBUTING.md
恭喜!🎉 你的 OpenFrame OSS Frontend 本地开发环境已经就绪,接下来就可以放心地在 apps/web 中开始探索与开发了。
