优学院(Ulearning)网课自动播放助手 — 自动连播、自动保存学习记录、自动处理「计时学习已暂停」弹窗。
A cross-platform Node.js CLI that drives your own Ulearning account through Playwright: it plays course videos, turns pages, saves study records early, and recovers from the platform's idle-timeout modal.
免责声明:本项目仅供个人学习与技术研究,请仅用于你本人已选、且允许自主安排学习时间的课程。使用自动化工具可能违反平台用户协议或学校的课程要求,由此产生的一切后果由使用者自行承担。
- 任意课程:只填课程链接,程序自动调用平台接口读取章节目录,不再需要手工整理
directory.json - 视频 + 文本页混合处理:按页面实际内容识别视频页,播完自动翻页
- 完成度不掉队:主动调用播放器的“保存进度”(
userSaveRecord()),播放中每 2 分钟保存一次,避免平台「每 5 分钟才自动保存」导致的误判 - 防走神暂停:每 60 秒向页面派发一次活动事件,重置平台的 10 分钟无操作计时;即使弹出了「计时学习已暂停」,也会自动点「继续学习」并恢复播放
- 登录会话自动续期:支持机构账号(学校/学号/密码)自动重登,也支持手动登录模式
- 崩溃自动重启:播放器卡死、页面无法前进、网络中断时自动重开会话
- 多课程排队:按配置顺序依次完成
- 可管理:
status看进度,stop优雅退出;日志与状态落盘 - 防睡眠:Windows / macOS / Linux 下尽力阻止系统休眠(失败不影响运行)
- Node.js 18+
- Google Chrome 或 Microsoft Edge(默认复用系统浏览器,无需额外下载)
- 也可以运行
npx playwright install chromium使用 Playwright 自带的 Chromium
支持 Windows / macOS / Linux。
git clone https://github.com/YOUR_NAME/ulearning-watch.git
cd ulearning-watch
npm install# 1. 生成配置文件
npx ulearning-watch init
# 2. 编辑 config.json:填写机构名称、学号、密码和课程链接
# 3. 先试运行:登录 + 读取目录,不观看
npx ulearning-watch watch --dry
# 4. 正式运行
npx ulearning-watch watchWindows 用户也可以直接双击仓库根目录的 start.bat / stop.bat。
在 Windows 上不保留控制台窗口、后台运行:
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\start-background.ps1在浏览器登录 优学院课程页,进入要学习的课程,复制地址栏中的整段链接,形如:
https://courseweb.ulearning.cn/ulearning/index.html#/course/textbook?courseId=167254
把整段链接填到 courses[].url 即可;也可以只填数字 courseId。
config.example.json 的完整字段:
| 字段 | 默认值 | 说明 |
|---|---|---|
browser.channel |
chrome |
浏览器类型:chrome / msedge / chromium |
browser.profileDir |
程序数据目录 | 持久化浏览器资料目录(保存登录 Cookie);相对路径基于配置文件位置 |
browser.muteAudio |
true |
静音播放 |
login.mode |
auto |
auto:有账号密码时自动登录,失败后转手动;manual:只等待手动登录 |
login.url |
优学院登录页 | 一般不用改 |
login.institution |
— | 机构名称,例如 武汉工程大学 |
login.account |
— | 学号 / 工号 |
login.password |
— | 密码 |
login.manualTimeoutSec |
600 |
自动登录失败后等待手动登录的秒数;0 表示不等待 |
courses[].name |
自动生成 | 课程显示名 |
courses[].url |
— | 课程链接或 courseId |
watch.playbackRate |
1 |
播放倍速,0.5 ~ 4。部分课程对倍速有额外要求,请谨慎调高 |
watch.saveIntervalSec |
120 |
播放中主动保存学习记录的间隔 |
watch.idleNudgeSec |
60 |
防走神活动事件的间隔(必须小于平台的 10 分钟阈值) |
watch.textSaveAfterSec |
20 |
文本页打开多久后主动保存一次记录 |
watch.textMaxWaitSec |
120 |
文本页最多等待多久仍未完成就前进 |
watch.noVideoWaitSec |
60 |
视频页迟迟没有 <video> 元素时的等待上限 |
watch.stallRestartAfterSec |
180 |
视频多久没有进度视为停滞 |
watch.stallFixes |
2 |
停滞时重开页面的次数 |
watch.maxReplays |
1 |
服务器仍未判定完成时最多重播次数 |
watch.pollSec |
10 |
主循环轮询间隔 |
watch.sessionRestartDelaySec |
15 |
会话出错后重启等待时间 |
watch.maxSessionRestarts |
0 |
单课程最多连续失败次数,0 表示不限 |
watch.studyLockRetrySec |
120 |
被其他学习会话占用时的重试等待时间 |
watch.maxStudyLockRetries |
5 |
连续被占用多少次后跳过该课程 |
keepAwake |
true |
尽力阻止系统休眠 |
log.level |
info |
debug / info / warn / error |
log.file |
程序数据目录 | 日志文件路径 |
优先级:环境变量 > 配置文件。
# macOS / Linux
export ULEARN_INSTITUTION='武汉工程大学'
export ULEARN_ACCOUNT='2607010302'
export ULEARN_PASSWORD='******'# Windows PowerShell
$env:ULEARN_INSTITUTION='武汉工程大学'
$env:ULEARN_ACCOUNT='2607010302'
$env:ULEARN_PASSWORD='******'
config.json已在.gitignore中,不要把包含账号密码的配置提交到 GitHub。
ulearning-watch watch # 依次观看配置中的所有课程
ulearning-watch watch --course 2 # 只观看第 2 门课程
ulearning-watch watch --course 167254 # 只观看 courseId=167254 的课程
ulearning-watch watch --course 职业发展 # 按课程名模糊匹配
ulearning-watch watch --dry # 只登录、读取目录并打印,不观看
ulearning-watch status # 查看是否在运行、当前页、完成计数
ulearning-watch stop # 发送停止请求,必要时强制结束进程树
ulearning-watch init --force # 重新生成配置文件--config <path> 可指定其他配置文件;--verbose 输出调试日志。
| 内容 | 位置 |
|---|---|
| 配置(默认) | ./config.json |
| 浏览器资料 | Windows:%LOCALAPPDATA%\ulearning-watch\profile;macOS:~/Library/Application Support/ulearning-watch;Linux:~/.local/state/ulearning-watch |
| 日志 | 同上目录下的 logs/watch.log |
| 运行状态 | 同上目录下的 state.json |
可用环境变量 ULEARN_HOME 改程序数据目录,用 ULEARN_PROFILE_DIR 单独改浏览器资料目录。
- 使用持久化 Chrome 资料目录启动浏览器,复用登录 Cookie。
- 打开课程页;会话过期时用机构账号登录,或等待手动登录。
- 点击「继续学习 / 开始学习」进入
learnCourse.html播放器,从地址中取得courseId / classId / chapterId。 - 在播放器页面内调用平台自己的接口
GET /course/stu/{courseId}/directory?classId=…获取完整章节目录(页面 id、relationid、contentType)。 - 主循环:
- 每 60 秒派发一次合成
mousemove/mousedown,重置平台NoAction的 10 分钟计时; - 检测
#alertModal,遇到「计时学习已暂停」自动点「继续学习」,并恢复视频播放; - 视频页:播放、每 2 分钟保存记录、播完后立即保存并校验完成状态;
- 文本页:打开后主动保存一次记录,等待平台标记完成;
- 通过「下一页」翻页,失败时回退到目录点击。
- 每 60 秒派发一次合成
- 平台完成判定为「已观看时长 / 视频时长 ≥ 95%」,本工具与平台自身的保存节奏配合,避免“播完了却判未完成”。
ulearning-watch/
├─ bin/ulearning-watch.js # CLI 入口
├─ src/
│ ├─ cli.js # 命令与参数解析
│ ├─ config.js # 配置加载、校验、课程筛选
│ ├─ logger.js # 日志
│ ├─ paths.js # 数据目录
│ ├─ state.js # 运行状态落盘
│ ├─ lock.js # 单实例锁、stop 支持
│ ├─ browser.js # 浏览器启动与回退
│ ├─ auth.js # 登录 / 会话续期
│ ├─ player.js # 播放器页面操作
│ ├─ directory.js # 课程目录获取与规范化
│ ├─ watcher.js # 观看主循环
│ └─ keepawake.js # 防睡眠
├─ test/ # node --test 单元测试
├─ config.example.json
├─ start.bat / stop.bat # Windows 便捷脚本
└─ README.md
浏览器启动失败
确认安装了 Chrome/Edge,或运行 npx playwright install chromium。若资料目录被其他 Chrome 进程占用,先关闭对应窗口。
登录失败 / 一直停在登录页
检查机构名称与学号密码;某些学校使用统一身份认证,无法用机构账号登录时,把 login.mode 改为 manual,程序会等待你在弹出的浏览器中手动登录。
一直卡在某个视频
查看日志 logs/watch.log。若视频内嵌了课中题,程序无法替你作答,会在多次尝试后强制前进;该页完成度取决于平台判定。
章节测验 / 讨论 / 作业
本工具只处理视频与普通文本页,不会作答任何测验。遇到需要人工完成的页面会跳过并记录日志。
需要一直开着电脑吗
需要。程序通过浏览器播放视频,关闭浏览器/终端即停止。keepAwake 会尽力阻止系统休眠。
会被判定为异常吗
本工具不修改平台数据,只模拟正常观看(播放、停页、保存)。但自动化本身可能被平台或学校视为违规,请自行评估风险。
能否多账号/多门课同时跑
同一资料目录只能运行一个实例;多门课程请在 courses 中排队,程序会依次处理。
欢迎提交 Issue / PR。修改前请先跑通 npm test。
npm test # 运行单元测试(不启动浏览器)
npm run dry # 真实登录 + 打印目录欢迎提交 Issue / PR。修改前请先跑通 npm test。