使用 Azure Static Web Apps 部署 Terrarium 静态 Web 应用：Web-Dev-For-Beginners 实战指南
Terrarium（虚拟盆栽）是 Web-Dev-For-Beginners 课程中第 3 个项目板块的产物：仅用 HTML、CSS 与少量 JavaScript 即可拖拽植物素材、组装一只玻璃罐生态盆栽的纯前端示例。本指南以其 部署指南文档（阿拉伯语译文，英文原版见 3-terrarium/README.md）为骨架，完整讲解如何借助 Azure Static Web Apps 把它发布到公网：从 Fork 仓库、触发 "Deploy to Azure" 向导，到关键配置项（App root、API 跳过、自动生成 .github 工作流）的逐项说明，并结合仓库内真实源码与已生成的工作流文件，说明这类无后端、无构建过程的静态应用到底是如何被自动构建和发布的。
一、Terrarium 是一个什么样的项目：先弄清"要部署什么"
在动手部署前，先明确这份教程要发布的对象。Terrarium 对应课程第 3 板块，其成果是一套"代码冥想"式的拖拽小应用，全部源码位于 3-terrarium/solution：
- index.html：页面结构。左右两个
.container容器（#left-container、#right-container）各放 7 个img.plant植物素材（plant1～plant14），中间#terrarium区域则用jar-top、jar-walls、dirt、jar-bottom等 div 拼出一个"玻璃罐"。 - style.css：全部视觉。罐壁（
.jar-walls）以半透明#d1e1df圆角矩形实现、侧栏（.container）固定width: 15%并绝对定位在左右两侧，罐子的圆角造型灵感来自 Jakub Mandra 的 glass jar CodePen（代码出处）。 - script.js：唯一交互逻辑。通过
dragElement()对 14 株植物逐一绑定onpointerdown/onpointermove/onpointerup，用闭包捕获pos1～pos4四个坐标变量实现拖拽（实现细节）。
关键结论对部署而言有三点，全部可以由源码直接印证：
- 纯静态：应用不依赖任何服务端语言与数据库，资源只有
.html/.css/.js与图片。 - 无 API：没有任何 fetch 或后端接口调用——这也是部署向导中"跳过 API 配置"的依据。
- 无构建步骤：CSS/JS 为手写原生文件、HTML 直接引用（
<link rel="stylesheet" href="./style.css">、<script src="./script.js" defer>），不存在编译/打包产物。
以上特性恰好完全命中 Azure Static Web Apps 的定位：为无服务器后端需求的静态站点提供全球托管、自动 TLS 证书与 GitHub Actions 驱动的持续部署。
二、部署前置条件与四步总览
依据 部署指南文档（及 解决方案自述 的英文原述），完整流程为以下四步：
- Fork 本仓库 到你自己的 GitHub 账号（部署向导会在你的 Fork 上创建用于构建发布的工作流文件，因此原仓库是只读的，必须以你自己的 Fork 为目标）。
- 点击文档中的 "Deploy to Azure" 按钮（原文档以
Deploy to Azure徽章形式给出，点击后会携带仓库信息跳转到 Azure 门户的静态 Web 应用创建向导）。 - 跟随设置向导创建应用，并完成下述三个关键配置。
- 等待 GitHub Actions 流水线首次运行完成，即可通过分配到的 URL 访问在线版 Terrarium。
三、向导中的三个关键配置项（务必理解每一项）
部署指南明确了配置向导中最重要、也最容易出错的三个点，逐条展开如下：
3.1 设置 App root（应用根目录）为 /solution 或代码库根目录
向导要求填写站点的"应用根目录"，即 Web 服务器应把哪个目录当作站点首页的所在位置。文档给出的合法取值有两个：
| 取值 | 适用场景 | 说明 |
|---|---|---|
/solution |
推荐 | 直接指向本教程现成可发布的 3-terrarium/solution，其中已包含可用的 index.html |
代码库根目录（/） |
当你把自己的页面放在仓库根目录时 | 需要自行组织文件，保证根目录存在作为入口的 HTML |
对于本教程推荐的 /solution，从 index.html 可以看到它恰好满足静态站点入口的全部要求：<!DOCTYPE html> 根文档直接位于该目录下，且对 ./style.css、./script.js、./images/plant*.png 的引用全部是相对路径——这正是关键：相对路径意味着把该目录整体"平移"到任意静态服务器根目录都能正常工作，无需改动任何一行代码。
3.2 本应用没有 API，跳过 API 配置
向导中通常有 API 路径（api_location）一栏。部署指南明确：此应用不含 API，因此直接跳过。这一点由源码可完整佐证——script.js 全文件仅处理指针事件实现拖拽，不存在任何 fetch/XMLHttpRequest/WebSocket 调用；index.html 中引入的唯一外部资源是 Font Awesome 图标字体的 CDN 链接（index.html），属浏览器侧资源加载，与站点后端无关。
3.3 .github 文件夹会被自动创建，驱动构建与发布
文档明确指出：配置完成后，一个 .github 文件夹会被自动生成，用于帮助 Azure Static Web Apps 的构建服务编译并发布应用。这并非虚构的描述——本仓库中恰好保留着一个由同类向导生成的现成工作流，可作为"生成产物长什么样"的一手证据（详见下一节）。
四、仓库内真实工作流文件解读：自动发布机制原理解析
在 .github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml 中，可以观察到 Azure Static Web Apps 向导在仓库中落地的工作流模板的真实形态，其核心结构如下（该文件是仓库中已存在的、为 quiz-app 生成的示例，用于说明向导产物格式，字段含义与教程描述一致）：
- 任务名称与触发条件：流水线名为
Azure Static Web Apps CI/CD；文件中的build_and_deploy_job定义了推送与 PR 场景下的构建部署任务，close_pull_request_job负责 PR 关闭后清理临时环境。 - 部署动作：核心步骤使用
Azure/static-web-apps-deploy@v1（workflow 第 16 行），这正是向导在.github目录中自动生成的关键动作。 - 三项路径配置字段（workflow 第 21-25 行）：
| 工作流字段 | 含义 | Terrarium 场景对应值 |
|---|---|---|
app_location |
应用源码路径，即向导中的 App root | /solution |
api_location |
API 源码路径；为空表示无 API | 留空（跳过 API 配置） |
output_location |
构建产物输出目录；本项目无构建步骤，可留空 | 留空（直接托管 app_location 内的 index.html） |
- 凭据注入：
azure_static_web_apps_api_token引用仓库 Secret（AZURE_STATIC_WEB_APPS_API_TOKEN_*），repo_token使用GITHUB_TOKEN用于在 PR 中回写部署评论——这些 Secret 均由向导自动配置，无需手动创建。
对照该模板即可理解：当你在自己的 Fork 上走完向导后，.github 下将出现一个把 app_location 指向 /solution、且 api_location/output_location 均为空的类似工作流；每次你向 Fork 的主分支推送代码，GitHub Actions 就会自动把 solution 目录发布为一个新的静态站点 URL，实现"推代码即上线"。
五、部署完成后的验证与持续更新
部署完成后，向导会返回形如 https://<name>.azurestaticapps.net 的站点地址。建议按以下清单验证：
- 打开站点 URL，确认标题
My Terrarium与玻璃罐正常渲染（对照 index.html 中的<header><h1>结构）。 - 从左右两侧容器拖拽任意植物（如
plant1～plant14）到罐中，观察 script.js 中闭包驱动的offsetTop/offsetLeft实时位移是否生效。 - 在浏览器开发者工具的 Network 面板确认
style.css、script.js、./images/plant*.png均以 200 返回且无 404——由于全部是相对路径引用，目录映射正确与否会在此刻暴露。
后续更新也非常简单：修改你的 Fork 中 3-terrarium/solution 下的 HTML/CSS/JS 并推送，触发工作流后站点即自动重建；如需临时预览修改效果，也可本地直接用浏览器打开 solution/index.html（纯静态文件无需本地服务器即可运行，这也是本项目与 Static Web Apps 天然契合的原因）。
六、常见问题与注意事项
- 不要把向导配置在原始仓库上：
.github工作流会写入仓库，必须使用你自己的 Fork；直接基于本教程所依赖的原仓库操作没有意义也无法写入。 - App root 与
app_location必须一一对应：若你选择代码库根目录而非/solution，请确认根目录下确有作为入口的 HTML 文件，否则站点会返回空白或 404。 - 不要臆造 API 配置：Terrarium 无后端，任何 API 路径填写都会让构建服务去查找并不存在的函数目录，从而失败——严格遵守文档"跳过 API 配置"的建议。
- 更新由推送触发：向导自动生成的工作流在每次向主分支推送（或合并 PR）时触发构建发布，未推送则站点保持上一次发布状态，属预期行为。
综上，在 Web-Dev-For-Beginners 的 Terrarium 课程中，你不仅完成了"用 HTML+CSS+JS 搭建交互应用"的练习，还通过 Azure Static Web Apps 走通了一条"零后端、零构建配置"的发布路径：Fork → Deploy 按钮 → 向导中设置 App root = /solution、跳过 API、接受自动生成的 .github 工作流。结合仓库内真实的工作流模板与源码，你可以清晰地把"部署向导中的每个字段"映射到"流水线中的每个动作"，从而举一反三地部署课程中的其他纯前端项目（如打字游戏、浏览器扩展的静态页面等）。
相关内容推荐
atomcodeClaude Code 的开源替代方案。连接任意大模型，编辑代码，运行命令，自动验证 — 全自动执行。用 Rust 构建，极致性能。 ｜ An open-source alternative to Claude Code. Connect any LLM, edit code, run commands, and verify changes — autonomously. Built in Rust for speed. Get StartedRust0624
Hy4-previewHy4 preview 是由腾讯混元团队研发的新一代混合专家（MoE）旗舰模型。模型总参数量 770B，每个 token 激活 49B，主干共包含78层，第一层采用标准 FFN，其余 77 层均为 MoE 结构，每层包含 256 个路由专家与 1 个共享专家，每个 token 激活 top-8 路由专家及共享专家。主干之外原生内置 1 层 MTP（总参数量 10B，激活 0.7B）以支持投机解码。Python00
GLM-5.3GLM-5.3 与 GLM-5.2 使用相同的基座模型——所有提升均来自后训练。与 GLM-5.2 相比，它在复杂编程和长程任务上的表现显著提升。Jinja00- GLM-5.3-FlashGLM-5.3-Flash (320B-A18B)，是GLM-5系列的首个原生多模态模型。320B总参数，能力超过GLM-5.2Jinja00
Spark-X2.5-4BSpark-X2.5-4B 旨在让强大的 AI 更实用、更高效、更易获得。在广泛日常任务中表现强劲，涵盖对话、写作、翻译、推理、编码、工具调用以及智能体工作流，并在同等规模的开源模型中取得领先成绩。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00- Spark-X2.5-1.7BSpark-X2.5-1.7B 旨在让强大的 AI 更加实用、高效且易于获取。这些模型在广泛的日常任务中表现出色，涵盖对话、写作、翻译、推理、编程、工具调用和智能体工作流，并在同等规模的开源模型中取得领先结果。Spark-X2.5 将面向效率的架构与最高 1M tokens 的原生上下文窗口相结合，并支持 200 多种语言。Python00
热门内容推荐
最新内容推荐
项目优选
kernel
pytorch
kernel
leetcode
ops-transformer
docs
jiuwenswarmcann-learning-hubops-nn
openGauss-server