Ontology Playground 部署指南：Azure Static Web Apps 完整配置教程-育师

Ontology Playground 部署指南：Azure Static Web Apps 完整配置教程

【免费下载链接】Ontology-PlaygroundFree, open-source web app for learning about ontologies and Microsoft Fabric IQ. Explore a catalogue of pre-built ontologies, design your own visually, export as RDF/XML, and share interactive diagrams. Zero backend, fully static.项目地址: https://gitcode.com/GitHub_Trending/on/Ontology-Playground

Ontology Playground是一款免费开源的本体论（Ontology）学习 Web 应用，可帮助你浏览预置本体目录、用可视化方式设计自己的本体、导出 RDF/XML 并分享交互式图表——且零后端、完全静态。本文将带你一步步完成Ontology Playground 部署，把它发布到Azure Static Web Apps，获得免费 HTTPS、全球 CDN 和 PR 预览环境等生产级能力。

为什么选择 Azure Static Web Apps 部署？

Ontology Playground 是纯静态站点（React + Vite 构建），天然适合托管在Azure Static Web Apps（简称 SWA）：

🚀免费额度：开发/生产计划免费，个人学习项目零成本
🔒自带 HTTPS 与全球 CDN，无需自己配置 Nginx 或对象存储
🔁PR 预览环境：每次拉取请求自动创建一个隔离预览站点，方便演示
⚙️原生支持 Azure Functions：项目中的 api/ 目录可一键部署为后端函数，用于可选的 AI 生成功能

部署前准备

开始之前，请确认你已经具备以下条件：

准备项	说明
Azure 账号	个人即可，Static Web Apps 有免费层
Node.js ≥ 18	本地构建验证用
Git	用于克隆仓库

第一步：克隆仓库并本地构建验证

先把代码拉到本地，确认构建流程没有问题，再去 Azure 上部署：

git clone https://gitcode.com/GitHub_Trending/on/Ontology-Playground cd Ontology-Playground npm install npm run build

构建成功后会生成build/目录——这是部署时的关键输出目录。可以在本地快速预览：

npm run preview

⚠️ 注意：Vite 默认输出目录是dist，但本项目在 vite.config.ts 中已配置outDir: 'build'，后续在 Azure 上填写构建配置时不要填错。

构建过程会依次执行两个编译脚本（定义于 package.json）：

catalogue:build—— 将 catalogue/ 目录下的本体 RDF 文件编译为catalogue.json
learn:build—— 将 content/learn/ 的教程文章编译为learn.json
tsc -b && vite build—— TypeScript 编译与 Vite 打包
build:embed—— 额外构建可嵌入的组件版本

第二步：在 Azure 门户创建 Static Web App

登录 Azure Portal，搜索并进入Static Web Apps，点击Create
选择订阅和资源组，填写应用名称（将成为你的免费子域名）
在Origin页面关联你的代码仓库，选择分支（推荐main）
关键构建配置如下表：

配置项	填写值	说明
Frameworks config	`Vite`	让 Azure 自动推断构建命令
App location	`/`（仓库根目录）	前端源码位置
App build path	`build`	与 vite.config.ts 中 outDir 一致
API location	`api`	可选，启用 AI 功能时必填

点击Review + create，部署通常 2~3 分钟完成，门户会分配一个*.azurestaticapps.net域名。

第三步：理解路由与安全配置

项目根目录已包含 staticwebapp.config.json，部署后会自动生效，无需额外操作。它做了三件重要的事：

SPA 路由回退：所有未匹配路径重写回index.html，保证前端路由刷新不 404
404 页面：自定义 404 也返回index.html并返回 200 状态码
安全响应头：内置 CSP、X-Frame-Options: DENY、Referrer-Policy等，提升生产环境安全性

如果你要修改安全策略，直接编辑该文件并推送即可，下次部署自动生效。

第四步（可选）：开启 AI 本体生成功能

Ontology Playground 内置一个可选的 AI 自然语言建本体功能，后端位于 api/generate-ontology/，依赖 Azure OpenAI。如果想启用它：

在 Azure 上创建Azure OpenAI资源，获取 Endpoint 和 API Key
在 Static Web Apps 的Settings → Environment variables中配置：

变量名	说明
`VITE_ENABLE_AI_BUILDER`	设为`true`，前端才会显示 AI 入口
`AZURE_OPENAI_ENDPOINT`	Azure OpenAI 资源端点
`AZURE_OPENAI_API_KEY`	对应的 API 密钥
`AZURE_OPENAI_DEPLOYMENT`	模型部署名，默认`gpt-4o-mini`

本地开发时可参考 api/local.settings.json.template 创建本地配置模板。

💡 如果不需要 AI 功能，保持默认即可——站点所有核心功能（目录浏览、可视化设计、RDF 导出、学习课程）完全无需后端。

第五步：验证部署与 PR 预览

打开 Azure 分配的域名，检查以下页面是否正常：
- 本体目录（Catalogue）能否加载预置本体
- 可视化设计器（Designer）能否拖拽建模
- 刷新任意子路由是否 404（验证 SPA 回退）
PR 预览环境：提交一个分支并发起 Pull Request，Azure 会自动生成一个独立的预览域名，方便给同事或老师演示
合并后，生产环境自动重新部署

常见问题排查 🛠️

现象	排查方法
页面空白，控制台 404	检查 Azure 上 App build path 是否填了`build`（不是`dist`）
静态资源加载失败	确认`Framework build command`包含`npm run build`，或手动填写完整命令
AI 按钮不显示	检查`VITE_ENABLE_AI_BUILDER`是否设为`true`，并在环境变量变更后重新触发部署
子路由刷新 404	确认 staticwebapp.config.json 已被一并部署