5分钟跑通OpenFrame OSS Frontend:本地开发环境快速搭建与验证指南

原创2026-10-27 09:21:561,995 阅读

5分钟跑通OpenFrame OSS Frontend:本地开发环境快速搭建与验证指南

OpenFrame OSS Frontend 是基于 Next.js(App Router)构建的开源 Web 前端,为 MSP(托管服务商)提供设备管理、工单系统、监控、脚本库和 AI 助手(Mingo AI)的一体化操作界面。本文是一份面向新手的本地开发环境搭建教程:只需 5 分钟,即可完成仓库克隆、依赖安装、环境变量配置,并通过 npm run dev 在 http://localhost:3000 跑通整个前端应用,最后用测试与类型检查完成环境验证。

OpenFrame OSS Frontend 开源项目的品牌标识,用于本地开发环境搭建指南

环境准备:检查 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 产物同步。

环境跑通之后,建议按以下路径继续深入:

恭喜!🎉 你的 OpenFrame OSS Frontend 本地开发环境已经就绪,接下来就可以放心地在 apps/web 中开始探索与开发了。

登录后查看全文
openframe-oss-frontend