ML-For-Beginners 配套测验应用：Vue 前端本地运行与 Azure Static Web Apps 部署实战

2026-09-07 19:41:48作者：戚魁泉Nursing

本指南围绕 ML-For-Beginners 机器学习课程仓库中的配套测验应用（quiz-app）展开，系统讲解该 Vue 单页应用的项目结构、本地开发命令，以及如何将其一键部署到 Azure Static Web Apps 并接入 GitHub Actions 实现持续交付。文章主体整理自仓库内 translations/bg/quiz-app/README.md（英文原版见 quiz-app/README.md），并补充仓库源码级的实现细节，读完即可在本地运行测验并完成云端发布。

一、应用定位：承载课程课前/课后测验的 Vue 前端

ML-For-Beginners 课程采用“每个主题一段视频 + 课前测验 + 课后测验”的教学节奏，配套的测验应用即仓库根目录下的 quiz-app 目录。它是一个纯前端单页应用（无后端 API），数据全部内嵌在本地 JSON 中，负责向学习者展示每个主题的两段测验。

从仓库源码结构可以还原出它的核心组成：

入口与启动：创建 Vue 实例并装配 vue-i18n（默认语言与回退语言均为 en）与路由；
路由定义：包含首页 /、测验页 /quiz/:id 以及兜底的 NotFound 路由；
测验组件：真正渲染题目、判断对错的核心组件；
首页视图：以链接列表形式列出所有测验；
题目数据：以 JSON 形式存放标题、题目、选项与正确答案。

值得注意的是测验数据全部来自 i18n 词条 quizzes：Home 与 Quiz 组件都通过 this.$t("quizzes") 读取，因此新增测验不需要改组件，只需往 JSON 中追加一个 quiz 对象即可。

二、项目结构与测验内容组织

测验应用采用经典 Vue CLI 工程布局，关键信息记录在 package.json：

依赖以 vue 与 vue-i18n、vue-router 为核心，构建由 @vue/cli-service 驱动；
脚本仅保留三条：serve（本地开发）、build（生产构建）、lint（静态检查）；
浏览器兼容目标（browserslist）为 > 1%、last 2 versions、not dead。

题目数据结构（见 en.json）为三层嵌套：

quizzes[].id          测验序号
quizzes[].title       测验标题（如 "Introduction to Machine Learning: Pre-Lecture Quiz"）
quizzes[].quiz[]      题目数组，每题含 questionText 与 answerOptions[]
answerOptions[].answerText   选项文案
answerOptions[].isCorrect    是否正确答案（"true"/"false" 字符串）

答题流程在 Quiz.vue 中实现：每次测验固定 3 道题，点击带 isCorrect == "true" 的选项才进入下一题，选错则显示“Sorry, try again”并要求重试；3 题全部答对后展示完成提示（$t("complete")）。这种“答对才前进”的设计保证了学习者在进入下一题前必须理解当前知识点。

三、多语言与按链接直达语言

测验应用内置了语言切换能力。国际化的词条文件位于 quiz-app/src/assets/translations，支持 en、tr、fr、ja、it、ptbr、es 共 7 种语言，由 index.js 统一汇入。

语言切换有两条路径（见 App.vue 顶栏的 locale 下拉框与 created() 钩子）：

在页面顶栏下拉框直接选择语言；
通过 URL 查询参数 ?loc=xx 预选语言——例如部署后访问 /quiz/1?loc=ja 可直达日语版本的测验（Quiz 组件同样读取了 $route.query.loc）。

由于仓库为多语言翻译仓库，各翻译目录（如 translations/bg/quiz-app/README.md）即使用该机制向不同语种学习者分发同一套测验体验。

四、本地环境搭建与运行

1. 安装依赖

在仓库根目录（包含 quiz-app/package.json 的位置）执行：

npm install

该命令会依据 package.json 安装 vue、vue-i18n、vue-router 及 @vue/cli-service 等依赖，并生成锁文件，保证后续构建环境一致。

2. 开发模式：编译 + 热重载

npm run serve

脚本实际执行 vue-cli-service serve，会启动本地开发服务器并监听文件变更做热重载（Hot Module Replacement），适合在编辑题目 JSON 或组件时即时预览效果。默认情况下浏览器访问终端输出的本地地址（通常为 http://localhost:8080）即可看到测验首页。

3. 生产构建：编译并压缩

npm run build

脚本实际执行 vue-cli-service build，产物默认输出到应用代码目录下的 dist/ 文件夹——这个路径与下文部署到 Azure 时的 Output Location 直接对应。Vue CLI 会在此过程中完成 JS/CSS 压缩、静态资源指纹化等工作。

4. 代码检查与修复

npm run lint

脚本实际执行 vue-cli-service lint，基于 package.json 中声明的 eslint:recommended 与 plugin:vue/essential 规则对源文件做静态检查，发现问题时自动修复可自动修复项。

五、部署到 Azure Static Web Apps

测验应用是纯静态站点，非常适合托管在 Azure Static Web Apps 上。官方文档给出的部署流程共六步，以下是结合本仓库结构的完整解读。

第 1 步：Fork GitHub 仓库

确保静态应用的代码位于你自己的 GitHub 仓库中：先 Fork 本仓库。Fork 之后，本仓库根目录下的 quiz-app 目录（含 package.json、src 等）即是你待部署的静态应用源码位置。

第 2 步：创建 Azure Static Web App

注册并登录 Azure 门户（创建 Azure 账户）；
点击 “Create a resource”，搜索 “Static Web App”；
点击 “Create” 进入创建向导。

第 3 步：配置静态 Web 应用

创建向导分为三组配置，各组含义如下表：

分组	配置项	填写说明
Basics（基础设置）	Subscription	选择你的 Azure 订阅
	Resource Group	新建或选择已有资源组
	Name	为静态 Web 应用命名
	Region	选择离你的用户最近的区域
Deployment details（部署信息）	Source	选择 “GitHub”
	GitHub Account	授权 Azure 访问你的 GitHub 账户
	Organization	选择你的 GitHub 组织
	Repository	选择包含静态应用代码的仓库
	Branch	选择要部署的分支
Build details（构建信息）	Build Presets	选择应用所用框架（本应用为 Vue.js）
	App Location	应用代码所在目录，本仓库即 `/quiz-app`（代码在根目录则填 `/`）
	API Location	如无后端 API 可留空（本应用为纯前端）
	Output Location	构建产物目录，即 `dist`

结合当前仓库的实际布局来解释这三处路径：测验应用的 package.json 位于仓库的 quiz-app/package.json，因此 App Location 填 /quiz-app；仓库中没有额外 API 服务，因此 API Location 留空；npm run build 由 package.json 中的 vue-cli-service build 触发，默认输出到 quiz-app/dist，因此 Output Location 填 dist（该路径相对于 App Location 解析）。

第 4 步：审阅并创建

检查上述配置无误后点击 “Create”。Azure 会自动创建所需资源，并在你 Fork 的仓库中生成 GitHub Actions workflow 文件（路径形如 .github/workflows/azure-static-web-apps-<name>.yml），该文件即后续构建与部署的自动化流水线。

第 5 步：认识 GitHub Actions Workflow

Azure 生成的 workflow 会自动接管构建与部署，并把部署令牌以 Secret 形式注入仓库。整理官方文档中的示例并修正注释格式后，等效的 workflow 文件如下：

name: Azure Static Web Apps CI/CD

on:
  push:
    branches:
      - main
  pull_request:
    types: [opened, synchronize, reopened, closed]
    branches:
      - main

jobs:
  build_and_deploy_job:
    runs-on: ubuntu-latest
    name: Build and Deploy Job
    steps:
      - uses: actions/checkout@v2
      - name: Build And Deploy
        id: builddeploy
        uses: Azure/static-web-apps-deploy@v1
        with:
          azure_static_web_apps_api_token: ${{ secrets.AZURE_STATIC_WEB_APPS_API_TOKEN }}
          repo_token: ${{ secrets.GITHUB_TOKEN }}
          action: "upload"
          app_location: "/quiz-app"  # 应用源码路径（本仓库）
          api_location: ""           # API 源码路径（本应用无 API，可留空）
          output_location: "dist"    # 构建产物目录（相对 App Location，可省略）

关键参数的含义：

azure_static_web_apps_api_token：由 Azure 在创建应用时自动写入仓库 Secret 的部署令牌，是流水线向 Azure 鉴权的凭据；
repo_token：使用 GitHub 自动提供的 GITHUB_TOKEN，用于授权部署操作读写仓库；
action: "upload"：执行上传构建产物的部署动作；当 pull_request 事件类型为 closed 时，官方实践中常改为 "close_pull_request" 以清理对应 PR 的预览环境；
app_location：指向含 package.json 的应用目录（本仓库为 /quiz-app）；
output_location：指向构建输出目录（dist），Azure 会将该目录内容作为静态站点对外发布。

触发条件方面，on.push 保证每次向 main 分支推送都会触发生产发布；on.pull_request 配合 types: [opened, synchronize, reopened, closed] 则会在 PR 打开、更新或关闭时触发，从而可为每次 PR 生成临时预览站点。

第 6 步：监控部署结果

进入 Fork 仓库的 “Actions” 标签页；
此时应能看到正在运行的 workflow，它会自动执行依赖安装、生产构建（npm run build）并部署到 Azure；
workflow 完成后，应用即上线于 Azure 提供的 URL（形如 https://<name>.<region>.azurestaticapps.net），学习者即可通过该链接访问课前/课后测验。

六、小结与注意事项

部署链路可概括为：Fork 仓库 → 创建 Azure Static Web App 并填写 Basics / Deployment details / Build details → Azure 自动生成 GitHub Actions workflow → 推送 main 分支或打开 PR 即触发构建与发布；
路径参数务必与实际仓库对齐：本仓库的 App Location 为 /quiz-app，Output Location 为 dist，API Location 留空；
测验内容与题目不依赖后端，全部维护在 quiz-app/src/assets/translations 的 JSON 词典中，改题只需编辑 JSON 并按常规流程提交，CI 会自动重新构建上线；
本地联调建议始终以 npm run serve 的开发服务器为准，部署前先执行一次 npm run build 与 npm run lint，确保 dist 产物完整且代码通过静态检查。