Building a website | 现代数学启蒙

slug

type

status

一. 建立本地临时网站：

win+r

cmd

cd D:\echo-vocab-web

python -m http.server 8000 (开通)

二.github网站开通：

好，这里我给你一套“傻瓜式 + 不踩坑”的完整发布到 GitHub 教程，就是针对你现在这套网页版项目

（index.html + app.js + style.css + ordered-words.txt）。

1、最终你会得到什么（先看结果）

✅ 一个 GitHub 仓库

✅ 一个 学生可直接访问的网址（GitHub Pages）

✅ 不需要服务器、不需要域名、不需要后台

2、第一步：在 GitHub 上建仓库（只做一次）

打开：https://github.com

右上角 ➜ New repository

填：

Repository name：例如

选择：Public

❌ 不要勾选 README（你本地已经有）

点 Create repository

⚠️ 创建完 先别关页面，等下要用到地址

3、第二步：整理你本地的文件结构（非常关键）

你的文件结构 必须是这样（一个文件夹）：

👉 index.html 必须在最外层（这是 GitHub Pages 的硬要求）

4、第三步：用 Git 推送到 GitHub（详细命令）

1️⃣ 打开命令行（在你的项目文件夹里）

在 Echo-Vocabulary-Web 文件夹 空白处：

Windows：Shift + 右键 → “在此处打开 PowerShell”

2️⃣ 初始化 Git（如果没初始化过）

3️⃣ 关联远程仓库（只做一次）

⚠️ 如果你之前看到：remote origin already exists，说明这一步已经做过

先检查：

如果已经有：

👉 直接跳到第 4️⃣ 步

如果没有，再执行（把仓库名换成你的）：

4️⃣ 提交并推送代码（核心步骤）

看到 一堆 uploading / done 就成功了 🎉

5、第四步：开启 GitHub Pages（给学生用）

打开你的仓库页面

点 Settings

左侧点 Pages

设置：

Source：Deploy from a branch

Branch：main

Folder：/ (root)

点 Save

等 10～30 秒

你会看到一行：

🎉🎉🎉

这就是学生访问的网址

三.github网站维护：

如何上传修改文件：

现在需要把这些更新同步到 GitHub 仓库。以下是 完整、最清晰、最安全的步骤，无论你之前有没有 push 成功，都可以直接用：

✅ 本地更新 → 推送到 GitHub 的标准流程

1. 打开命令行，进入你的项目目录

✅ 2. 查看当前状态

你会看到：

修改的文件（modified）

新增的文件（untracked）

✅ 3. 把所有修改加入暂存区

✅ 4. 提交（写提交信息）

如果显示 “nothing to commit”，说明你没有新的改动。

✅ 5. 推送到 GitHub

你之前已经 git remote add origin ... 过，所以直接推送即可：

如果出现认证窗口（Git Credential Manager），按照提示登录即可。

四. 将网站打包成exe(用户可以离线使用)：

下面是一份**“从你当前文件夹（index.html/app.js/style.css/audio/sentence.txt）→ 打包成 Windows 可离线运行的 exe”** 的完整 Electron 教程（Windows 10/11 适用）。

我会按你这个项目的实际结构来写（你现在的入口是 index.html，逻辑在 app.js，样式在 style.css，并且通过 fetch('sentence.txt') 读取题库、用 new Audio(item.audio) 播放音频）。

0. 你需要先装好两个东西

Node.js LTS（建议 18 或 20）

装完后打开 PowerShell，确认：

建议用 VS Code（可选，但更方便）

1. 整理你的当前文件夹（保持你现在的结构）

假设你的项目现在是这样（非常标准）：

✅ 不需要把网页改成 Java 项目
✅ 不需要改你现有业务逻辑（进度 localStorage、播放音频等）

2. 在项目根目录初始化 Electron 外壳

在 EchoDictationWeb/ 根目录打开 PowerShell：

然后安装 3 个依赖（Electron + 打包工具 + 本地静态服务器）：

说明：

electron：桌面外壳

electron-builder：一键打包成 exe

http-server：关键点！让你的 fetch('sentence.txt') 在离线 exe 里也能稳定工作

（因为 file:// 直开时，浏览器/Chromium 对 fetch 本地文件经常会有跨域限制）

3. 新建 Electron 主进程文件 `main.js`

在根目录新建 main.js，内容如下（直接复制粘贴）：

4. 修改 `package.json`（关键）

打开根目录的 package.json，把它改成类似这样（重点是 scripts 和 build）：

说明：

"files": ["**/*"] 会把你的 index.html/app.js/style.css/sentence.txt/audio/ 全带进去

target: nsis 会生成 Windows 安装包（安装后是 exe 程序）

oneClick:false 方便学校电脑自己选择安装路径

你之前说“不是 msi 要 exe”：Electron 的常规是 NSIS 安装器（用户最终也是 exe 程序离线运行），比 msi 更常用。

5. 先本地运行测试（非常重要）

在根目录执行：

看到窗口打开，检查：

能正常弹出姓名输入（你 app.js 启动就触发 start）

能读取 sentence.txt（状态显示题库句数）

能播放 audio/1907.mp3 这类音频

如果这里都 OK，再打包。

6. 一键打包成 exe

运行：

打包完成后，你会看到：

这个 Setup.exe 发给学生即可：

双击安装

桌面出现 EchoDictation 快捷方式

断网也能用（因为资源全在本机）

7. 给学生离线分发时的建议（避免踩坑）

A) “题库 sentence.txt + audio” 怎么更新？

你有两种方式：

每次更新重新打包发新安装包（最省心）

把题库做成外置文件（高级玩法：让 exe 从安装目录旁读取 sentence.txt/audio，以后只替换文件即可）

你如果需要我可以再给你“外置资源版”的打包配置。

B) 进度保存在哪里？

你现在用 localStorage 保存用户进度（按姓名区分）。

Electron 会把它保存在系统的用户数据目录中（对学生透明），离线稳定。

C) 校园机权限问题

如果学生电脑没有管理员权限：

你可以改成生成 portable 免安装版（我也能给你配）——解压即用。

8. 常见错误与解决

1) 打包后打开黑屏 / 一闪而过

通常是 main.js 出错。你可以：

临时在 createWindow 后加 win.webContents.openDevTools() 看控制台报错

或者告诉我报错截图/日志，我按错误点修

2) 音频打包后找不到

确认 audio 目录在根目录，并且你的 sentence.txt 里音频路径是类似：

这与你现在的 new Audio(item.audio) 一致。

你如果想我“更进一步帮你一把”

你把你当前文件夹再补充上传一个 sentence.txt（或贴几行格式），我可以：

顺手帮你做一个 可直接运行的 Electron 工程结构

并给你一份“打包后学生怎么安装、怎么更新题库”的一页说明书（你直接发班级群）

只要你回我：你希望做“安装版（NSIS）”还是“免安装绿色版（portable）”？ 我就按你选的直接给你最终配置。