尧图网站建设 
简介Blackboard Downloader 是一款基于 Java 开发的课程文档批量下载工具面向需要从 Blackboard 教学平台批量获取课程资料的高校学生与教师。它通过输入 Blackboard 用户名和密码自动抓取所有课程文档并按平台原有结构组织文件教学大纲归入「教学大纲」文件夹、当年作业归入「作业」文件夹课程内容等模块同样保持对应层级便于离线查阅与归档。资源包为 zip 格式整体约 51.56MB内含 Java 源码、可执行 jar 包、登录信息配置及自述文件等源码便于二次开发与功能调整。工具仅深入一层子文件夹即导航到课程内容后需再点击进入的文件夹会完整下载但不会继续向下递归这一边界在描述中有明确说明。目前已有 234 人学习下载适合需要批量整理课程资料、减少重复点击下载操作的用户参考使用。1. 从手动点几十次到一条命令BlackboardDownloader 到底解决什么每到期末Blackboard 上那堆课程文档就成了折磨一门课十几个文件夹每层还嵌着 PDF、PPT、Word、Excel点进去、下载、返回、再点下一层几十次鼠标操作下来人已经麻了。BlackboardDownloader 这个方向要干的事很直接——把「在黑板上下载所有课程的所有文档」这件事从手工点击变成一次配置、一条命令跑完。它面向的是被课程资料淹没的学生、助教以及需要批量归档教学材料的老师。核心诉求就三个能自动遍历课程和文件夹、能把文档按课程结构落到本地、能重复跑而不用每次重新登录。这篇笔记就按「它靠什么跑通 → 怎么落地 → 坑在哪 → 怎么进阶」的顺序把可复现的路径讲清楚。需要先说明一个前提Blackboard 各校部署的版本、域名、是否开了 API、是否强制 SSO差异极大。所以下面讲的是一套通用可迁移的方案骨架具体到你自己学校时参数要按实际情况调。我不会假装见过某个具体仓库的源码而是把这类下载器最常见的实现方式拆开讲让你能自己搭起来或者看懂手头的工具。2. 先搞懂 Blackboard 的文档藏在哪三种取数路径的选型在动手写代码之前得先弄清楚「文档」在 Blackboard 里到底以什么形式存在。搞错了取数路径后面全是白费功夫。Blackboard 的课程内容大体分三层课程Course→ 内容区Content Area比如 Course Documents、Assignments→ 具体条目Item / File / Folder。文档可能挂在任意一层而且很多是嵌套文件夹。取数路径常见有三种选哪种直接决定你的实现难度和稳定性。2.1 REST API、页面抓取、导出包三条路各自的边界第一条是 Blackboard Learn REST API。较新的 Blackboard Learn 版本提供/learn/api/public/v1/系列接口能拿到课程列表、内容区、附件元数据。优点是结构化、稳定、有官方文档缺点是很多学校根本没给普通学生开 API 权限或者只对管理员开放你拿不到 token。判断方法很简单问学校 IT 或者试一下能不能申请到 REST 应用的 key/secret。拿不到就直接放弃这条路。第二条是页面抓取HTML 解析。登录后课程页面本质是一堆 HTML文档链接藏在a href里指向/bbcswebdav/这类路径。这条路通用性最强几乎所有部署都能用代价是要处理登录态、动态渲染和链接去重。绝大多数 BlackboardDownloader 走的就是这条。第三条是课程导出包。Blackboard 允许教师把课程导出成 IMS Common Cartridge.imscc或内容包里面打包了所有文件。如果你能拿到导出权限这是最省事的——一个 zip 解压就是全部文档。但学生通常没这个权限所以它更多是教师/助教场景的选择。路径适用角色稳定性实现难度前置条件REST API管理员/有授权的开发者高中拿到 API key页面抓取学生/助教中中高能登录、能解析 HTML导出包教师/助教高低有导出权限选型建议先花十分钟确认你有没有 API 或导出权限没有就老老实实走页面抓取。别一上来就写爬虫先确认权限能省掉大量返工。2.2 登录态怎么维持会话 Cookie 是命根子页面抓取路线的第一个坎是登录。Blackboard 登录后靠会话 Cookie 维持身份你后续所有请求都得带上它。最稳的做法不是用脚本模拟账号密码登录很多学校有 SSO、验证码、双因素模拟登录极易翻车而是手动登录一次把 Cookie 导出给脚本用。具体操作浏览器登录 Blackboard 后打开开发者工具 → Application/存储 → Cookies找到你学校域名下的会话 Cookie常见名字如JSESSIONID、BbRouter、session_id等复制出来。或者更省事用浏览器插件导出 Cookie 为 JSON。脚本读取这份 Cookie构造请求头即可。import requests # 从浏览器导出的 Cookie 字符串形如 JSESSIONIDxxx; BbRouteryyy COOKIE_STR JSESSIONID你的值; BbRouter你的值 BASE_URL https://你的学校域名 headers { Cookie: COOKIE_STR, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64), } # 先验证登录态是否有效请求课程列表页看是否被重定向到登录页 resp requests.get(f{BASE_URL}/webapps/portal/execute/tabs/tabAction, headersheaders, allow_redirectsFalse) print(resp.status_code, resp.headers.get(Location))这段代码的逻辑是带上 Cookie 请求一个需要登录的页面如果返回 302 且 Location 指向登录页说明 Cookie 过期了得重新导出。参数说明allow_redirectsFalse是关键默认 requests 会自动跟随重定向那样你只会看到登录页的 200误以为登录成功。关掉自动重定向才能从状态码和 Location 判断真实登录态。User-Agent建议和导出 Cookie 的浏览器保持一致减少被风控的概率。提示Cookie 有效期通常几小时到几天不等跑批量下载前先验证一次别跑到一半发现掉线了。2.3 课程与文档的遍历逻辑先拿课程 ID再递归内容区登录态搞定后遍历逻辑分两步。第一步拿到你所有课程的 ID 或访问 URL。Blackboard 的课程列表一般在门户首页或/webapps/portal/execute/tabs/tabAction返回的 HTML 里每门课对应一个course_id形如_12345_1或直接是课程主页链接。第二步对每门课请求它的内容区页面解析出所有文档链接遇到文件夹就递归进去。这里有个容易忽略的点Blackboard 的文件夹展开往往是 AJAX 请求不是静态 HTML。你直接请求课程主页可能只看到顶层文件夹里面的内容要再发一次请求。常见做法是找到文件夹对应的content_id请求类似/webapps/blackboard/content/listContent.jsp?course_idxxxcontent_idyyy的地址拿到子层 HTML 再解析。递归时一定要记录已访问的content_id否则遇到循环引用会无限递归——这是血泪经验我第一次写就踩过。3. 把下载器跑起来从解析 HTML 到落盘的完整链路原理清楚了这一章落到能跑的代码。整条链路是解析课程页 → 提取文档链接 → 下载文件 → 按课程结构落盘 → 断点续传。每一步都有细节我按顺序拆。3.1 用 BeautifulSoup 提取文档链接与文件夹Blackboard 的文档链接通常指向/bbcswebdav/路径或者带xid、content_id参数的下载地址。文件夹链接则指向listContent.jsp。用 BeautifulSoup 解析时要同时抓这两类并区分开。from bs4 import BeautifulSoup from urllib.parse import urljoin, urlparse, parse_qs def parse_content_page(html, base_url): 解析一个内容区页面返回 (文档链接列表, 子文件夹列表) soup BeautifulSoup(html, html.parser) files, folders [], [] for a in soup.find_all(a, hrefTrue): href a[href] full urljoin(base_url, href) # 文档指向 bbcswebdav 或带 download 参数 if /bbcswebdav/ in full or download in full.lower(): files.append({url: full, name: a.get_text(stripTrue)}) # 文件夹指向 listContent.jsp 且带 content_id elif listContent.jsp in full and content_id in full: qs parse_qs(urlparse(full).query) folders.append({ url: full, content_id: qs.get(content_id, [])[0], name: a.get_text(stripTrue), }) return files, folders逻辑说明urljoin把相对链接补成绝对链接因为 Blackboard 页面里大量用相对路径。判断文档用/bbcswebdav/这个特征路径这是 Blackboard 存文件的经典位置判断文件夹用listContent.jsp加content_id参数。参数上a.get_text(stripTrue)拿链接文字当文件名但要注意 Blackboard 的链接文字经常带多余空格或图标文字后面落盘时还得清洗。3.2 递归遍历与去重避免无限循环拿到文件夹列表后递归。核心是维护一个visited集合记录已处理的content_id。def crawl_course(session, course_url, headers, visitedNone, depth0): 递归遍历一门课的所有内容区 if visited is None: visited set() if depth 10: # 防御性深度限制 return [], [] resp session.get(course_url, headersheaders) files, folders parse_content_page(resp.text, course_url) all_files list(files) for folder in folders: cid folder[content_id] if cid in visited: continue visited.add(cid) sub_files, _ crawl_course(session, folder[url], headers, visited, depth 1) all_files.extend(sub_files) return all_files, folders逻辑说明visited用content_id去重防止同一文件夹被反复抓。depth 10是防御性限制正常课程不会嵌套这么深一旦触发说明逻辑有问题早点停比无限递归好。参数上session用requests.Session()复用连接和 Cookie比每次新建请求快很多也更像正常浏览器行为。3.3 下载与落盘文件名清洗和目录结构下载时最容易翻车的是文件名。Blackboard 的链接文字可能包含/ \ : * ? |这些在 Windows 上非法的字符还有超长文件名、重名文件。落盘前必须清洗。import os import re def safe_filename(name, max_len120): 清洗文件名去掉非法字符并限长 name re.sub(r[\\/:*?|\r\n\t], _, name).strip() name re.sub(r\s, , name) if len(name) max_len: base, ext os.path.splitext(name) name base[:max_len - len(ext)] ext return name or unnamed def download_file(session, url, save_path, headers): 流式下载支持大文件 os.makedirs(os.path.dirname(save_path), exist_okTrue) if os.path.exists(save_path) and os.path.getsize(save_path) 0: return skipped # 断点续传已存在就跳过 with session.get(url, headersheaders, streamTrue, timeout60) as r: r.raise_for_status() with open(save_path, wb) as f: for chunk in r.iter_content(chunk_size8192): f.write(chunk) return done逻辑说明safe_filename把非法字符替换成下划线压缩连续空白超长时保留扩展名截断主体。download_file用streamTrue流式下载避免大文件一次性读进内存os.path.exists判断实现最简单的断点续传——已下载的非空文件直接跳过重跑时不会重复下载。参数上chunk_size8192是通用值网络差可以调小本地快可以调大到 65536。timeout60防止某个请求卡死拖垮整个任务。目录结构建议按「课程名/内容区名/文件名」组织这样下载完打开就是清晰的课程归档而不是一堆散文件。课程名从课程页标题提取内容区名从文件夹链接文字提取同样要过一遍safe_filename。3.4 限速与重试别把学校服务器打挂批量下载几十上百个文件如果不加控制很容易触发服务器限流甚至被封 IP。加个简单限速和重试。import time from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def build_session(): session requests.Session() retry Retry(total3, backoff_factor1.5, status_forcelist[429, 500, 502, 503, 504]) session.mount(https://, HTTPAdapter(max_retriesretry)) return session # 每个文件下载之间 sleep控制节奏 for f in all_files: download_file(session, f[url], path, headers) time.sleep(1.0) # 每秒一个按需调整逻辑说明Retry对 429限流和 5xx 错误自动重试backoff_factor1.5让重试间隔指数增长避免密集重试。time.sleep(1.0)是主动限速1 秒一个文件对几百个文件来说也就几分钟但能大幅降低被封风险。参数上如果文件特别多可以调到 0.5 秒如果服务器响应慢反而要调大避免堆积。4. 避坑与排查那些让我重跑整晚的坑这一章全是踩过的坑每条按「现象 → 原因 → 解决」写照着排查能省你几个通宵。4.1 下载下来的全是登录页 HTML现象文件下下来了但打开一看是登录页的 HTML大小都差不多几百字节。原因Cookie 过期或没带上请求被重定向到登录页而你的代码把重定向后的 HTML 当文件存了。解决下载前先做一次登录态验证见 2.2 的代码并且在download_file里检查Content-Type如果是text/html且文件本该是 PDF/PPT就报警而不是落盘。4.2 文件夹递归到一半就停了现象顶层文件下完了子文件夹里的一个都没有。原因Blackboard 的文件夹展开是 AJAX静态请求课程主页拿不到子层内容或者content_id提取错了。解决确认文件夹链接确实带content_id并且请求的是listContent.jsp而不是主页必要时用浏览器开发者工具的 Network 面板看点击文件夹时实际发了什么请求照着构造。4.3 文件名乱码或变成一串百分号编码现象下载的文件名是%E8%AF%BE%E7%A8%8B.pdf这种。原因链接文字或 URL 里的中文没做 URL 解码。解决对文件名用urllib.parse.unquote()解码再走safe_filename清洗。如果服务器返回的Content-Disposition头里有文件名优先用它比链接文字准。4.4 跑到一半 Cookie 失效后面全失败现象前几十个文件正常后面全是登录页。原因会话 Cookie 有有效期批量任务跑太久就过期了。解决在下载循环里定期比如每 20 个文件做一次登录态检查失效就暂停并提示重新导出 Cookie或者把任务拆成小批次每批重新验证。4.5 重名文件互相覆盖现象同一门课里两个不同文件夹有同名文件下载完只剩一个。原因落盘路径没带足够的层级信息或者同名直接覆盖。解决目录结构带上内容区名路径形如课程/内容区/文件名如果同一层还有重名在文件名后追加短哈希或序号。5. 进阶让下载器更省心、更可验证的几个技巧基础版跑通后可以往上加几个提升体验的东西。第一个是增量同步把已下载文件的 URL 或content_id记到一个本地 JSON 里下次跑只下新增的。这样每周跑一次就能保持课程资料最新不用全量重下。实现上就是在download_file前查一下记录下载成功后写回。第二个是并发下载。单线程一秒一个文件几百个文件要十几分钟。用concurrent.futures.ThreadPoolExecutor开 3 到 5 个线程并发速度能提升几倍但别开太多否则容易触发限流。配合前面的重试机制稳定性也够。from concurrent.futures import ThreadPoolExecutor def download_task(f): download_file(session, f[url], build_path(f), headers) return f[name] with ThreadPoolExecutor(max_workers4) as pool: results list(pool.map(download_task, all_files)) print(f完成 {len(results)} 个文件)参数上max_workers4是保守值学校服务器扛得住可以到 8但一定要配合重试和限速否则并发越高越容易被封。第三个是验证下载完整性。跑完后统计一下预期文件数 vs 实际落盘数总大小是否合理有没有 0 字节文件。写个简单的校验脚本比人眼翻目录靠谱得多。校验项判断方法异常处理文件数对比解析出的链接数少了就查日志找失败项文件大小检查 0 字节文件重新下载该文件文件类型检查扩展名与 Content-Type不符则可能是登录页最后一个技巧是把配置外置。域名、Cookie、课程 ID、保存路径、限速参数全写到一个config.yaml或环境变量里代码不动换学校换学期只改配置。这样这套东西能跟着你从一门课用到毕业甚至分享给同学时他们只改自己的 Cookie 就行。我自己现在的习惯是每学期开学跑一次全量之后每周跑一次增量配置和 Cookie 单独存代码基本不动。踩过的坑大多集中在登录态和文件名上把这两块做扎实剩下的就是耐心等它跑完。希望帮到你。本文还有配套的精品资源点击获取 BlackboardDownloader：一键批量下载Blackboard课程文档的实战指南
简介Blackboard Downloader 是一款基于 Java 开发的课程文档批量下载工具面向需要从 Blackboard 教学平台批量获取课程资料的高校学生与教师。它通过输入 Blackboard 用户名和密码自动抓取所有课程文档并按平台原有结构组织文件教学大纲归入「教学大纲」文件夹、当年作业归入「作业」文件夹课程内容等模块同样保持对应层级便于离线查阅与归档。资源包为 zip 格式整体约 51.56MB内含 Java 源码、可执行 jar 包、登录信息配置及自述文件等源码便于二次开发与功能调整。工具仅深入一层子文件夹即导航到课程内容后需再点击进入的文件夹会完整下载但不会继续向下递归这一边界在描述中有明确说明。目前已有 234 人学习下载适合需要批量整理课程资料、减少重复点击下载操作的用户参考使用。1. 从手动点几十次到一条命令BlackboardDownloader 到底解决什么每到期末Blackboard 上那堆课程文档就成了折磨一门课十几个文件夹每层还嵌着 PDF、PPT、Word、Excel点进去、下载、返回、再点下一层几十次鼠标操作下来人已经麻了。BlackboardDownloader 这个方向要干的事很直接——把「在黑板上下载所有课程的所有文档」这件事从手工点击变成一次配置、一条命令跑完。它面向的是被课程资料淹没的学生、助教以及需要批量归档教学材料的老师。核心诉求就三个能自动遍历课程和文件夹、能把文档按课程结构落到本地、能重复跑而不用每次重新登录。这篇笔记就按「它靠什么跑通 → 怎么落地 → 坑在哪 → 怎么进阶」的顺序把可复现的路径讲清楚。需要先说明一个前提Blackboard 各校部署的版本、域名、是否开了 API、是否强制 SSO差异极大。所以下面讲的是一套通用可迁移的方案骨架具体到你自己学校时参数要按实际情况调。我不会假装见过某个具体仓库的源码而是把这类下载器最常见的实现方式拆开讲让你能自己搭起来或者看懂手头的工具。2. 先搞懂 Blackboard 的文档藏在哪三种取数路径的选型在动手写代码之前得先弄清楚「文档」在 Blackboard 里到底以什么形式存在。搞错了取数路径后面全是白费功夫。Blackboard 的课程内容大体分三层课程Course→ 内容区Content Area比如 Course Documents、Assignments→ 具体条目Item / File / Folder。文档可能挂在任意一层而且很多是嵌套文件夹。取数路径常见有三种选哪种直接决定你的实现难度和稳定性。2.1 REST API、页面抓取、导出包三条路各自的边界第一条是 Blackboard Learn REST API。较新的 Blackboard Learn 版本提供/learn/api/public/v1/系列接口能拿到课程列表、内容区、附件元数据。优点是结构化、稳定、有官方文档缺点是很多学校根本没给普通学生开 API 权限或者只对管理员开放你拿不到 token。判断方法很简单问学校 IT 或者试一下能不能申请到 REST 应用的 key/secret。拿不到就直接放弃这条路。第二条是页面抓取HTML 解析。登录后课程页面本质是一堆 HTML文档链接藏在a href里指向/bbcswebdav/这类路径。这条路通用性最强几乎所有部署都能用代价是要处理登录态、动态渲染和链接去重。绝大多数 BlackboardDownloader 走的就是这条。第三条是课程导出包。Blackboard 允许教师把课程导出成 IMS Common Cartridge.imscc或内容包里面打包了所有文件。如果你能拿到导出权限这是最省事的——一个 zip 解压就是全部文档。但学生通常没这个权限所以它更多是教师/助教场景的选择。路径适用角色稳定性实现难度前置条件REST API管理员/有授权的开发者高中拿到 API key页面抓取学生/助教中中高能登录、能解析 HTML导出包教师/助教高低有导出权限选型建议先花十分钟确认你有没有 API 或导出权限没有就老老实实走页面抓取。别一上来就写爬虫先确认权限能省掉大量返工。2.2 登录态怎么维持会话 Cookie 是命根子页面抓取路线的第一个坎是登录。Blackboard 登录后靠会话 Cookie 维持身份你后续所有请求都得带上它。最稳的做法不是用脚本模拟账号密码登录很多学校有 SSO、验证码、双因素模拟登录极易翻车而是手动登录一次把 Cookie 导出给脚本用。具体操作浏览器登录 Blackboard 后打开开发者工具 → Application/存储 → Cookies找到你学校域名下的会话 Cookie常见名字如JSESSIONID、BbRouter、session_id等复制出来。或者更省事用浏览器插件导出 Cookie 为 JSON。脚本读取这份 Cookie构造请求头即可。import requests # 从浏览器导出的 Cookie 字符串形如 JSESSIONIDxxx; BbRouteryyy COOKIE_STR JSESSIONID你的值; BbRouter你的值 BASE_URL https://你的学校域名 headers { Cookie: COOKIE_STR, User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64), } # 先验证登录态是否有效请求课程列表页看是否被重定向到登录页 resp requests.get(f{BASE_URL}/webapps/portal/execute/tabs/tabAction, headersheaders, allow_redirectsFalse) print(resp.status_code, resp.headers.get(Location))这段代码的逻辑是带上 Cookie 请求一个需要登录的页面如果返回 302 且 Location 指向登录页说明 Cookie 过期了得重新导出。参数说明allow_redirectsFalse是关键默认 requests 会自动跟随重定向那样你只会看到登录页的 200误以为登录成功。关掉自动重定向才能从状态码和 Location 判断真实登录态。User-Agent建议和导出 Cookie 的浏览器保持一致减少被风控的概率。提示Cookie 有效期通常几小时到几天不等跑批量下载前先验证一次别跑到一半发现掉线了。2.3 课程与文档的遍历逻辑先拿课程 ID再递归内容区登录态搞定后遍历逻辑分两步。第一步拿到你所有课程的 ID 或访问 URL。Blackboard 的课程列表一般在门户首页或/webapps/portal/execute/tabs/tabAction返回的 HTML 里每门课对应一个course_id形如_12345_1或直接是课程主页链接。第二步对每门课请求它的内容区页面解析出所有文档链接遇到文件夹就递归进去。这里有个容易忽略的点Blackboard 的文件夹展开往往是 AJAX 请求不是静态 HTML。你直接请求课程主页可能只看到顶层文件夹里面的内容要再发一次请求。常见做法是找到文件夹对应的content_id请求类似/webapps/blackboard/content/listContent.jsp?course_idxxxcontent_idyyy的地址拿到子层 HTML 再解析。递归时一定要记录已访问的content_id否则遇到循环引用会无限递归——这是血泪经验我第一次写就踩过。3. 把下载器跑起来从解析 HTML 到落盘的完整链路原理清楚了这一章落到能跑的代码。整条链路是解析课程页 → 提取文档链接 → 下载文件 → 按课程结构落盘 → 断点续传。每一步都有细节我按顺序拆。3.1 用 BeautifulSoup 提取文档链接与文件夹Blackboard 的文档链接通常指向/bbcswebdav/路径或者带xid、content_id参数的下载地址。文件夹链接则指向listContent.jsp。用 BeautifulSoup 解析时要同时抓这两类并区分开。from bs4 import BeautifulSoup from urllib.parse import urljoin, urlparse, parse_qs def parse_content_page(html, base_url): 解析一个内容区页面返回 (文档链接列表, 子文件夹列表) soup BeautifulSoup(html, html.parser) files, folders [], [] for a in soup.find_all(a, hrefTrue): href a[href] full urljoin(base_url, href) # 文档指向 bbcswebdav 或带 download 参数 if /bbcswebdav/ in full or download in full.lower(): files.append({url: full, name: a.get_text(stripTrue)}) # 文件夹指向 listContent.jsp 且带 content_id elif listContent.jsp in full and content_id in full: qs parse_qs(urlparse(full).query) folders.append({ url: full, content_id: qs.get(content_id, [])[0], name: a.get_text(stripTrue), }) return files, folders逻辑说明urljoin把相对链接补成绝对链接因为 Blackboard 页面里大量用相对路径。判断文档用/bbcswebdav/这个特征路径这是 Blackboard 存文件的经典位置判断文件夹用listContent.jsp加content_id参数。参数上a.get_text(stripTrue)拿链接文字当文件名但要注意 Blackboard 的链接文字经常带多余空格或图标文字后面落盘时还得清洗。3.2 递归遍历与去重避免无限循环拿到文件夹列表后递归。核心是维护一个visited集合记录已处理的content_id。def crawl_course(session, course_url, headers, visitedNone, depth0): 递归遍历一门课的所有内容区 if visited is None: visited set() if depth 10: # 防御性深度限制 return [], [] resp session.get(course_url, headersheaders) files, folders parse_content_page(resp.text, course_url) all_files list(files) for folder in folders: cid folder[content_id] if cid in visited: continue visited.add(cid) sub_files, _ crawl_course(session, folder[url], headers, visited, depth 1) all_files.extend(sub_files) return all_files, folders逻辑说明visited用content_id去重防止同一文件夹被反复抓。depth 10是防御性限制正常课程不会嵌套这么深一旦触发说明逻辑有问题早点停比无限递归好。参数上session用requests.Session()复用连接和 Cookie比每次新建请求快很多也更像正常浏览器行为。3.3 下载与落盘文件名清洗和目录结构下载时最容易翻车的是文件名。Blackboard 的链接文字可能包含/ \ : * ? |这些在 Windows 上非法的字符还有超长文件名、重名文件。落盘前必须清洗。import os import re def safe_filename(name, max_len120): 清洗文件名去掉非法字符并限长 name re.sub(r[\\/:*?|\r\n\t], _, name).strip() name re.sub(r\s, , name) if len(name) max_len: base, ext os.path.splitext(name) name base[:max_len - len(ext)] ext return name or unnamed def download_file(session, url, save_path, headers): 流式下载支持大文件 os.makedirs(os.path.dirname(save_path), exist_okTrue) if os.path.exists(save_path) and os.path.getsize(save_path) 0: return skipped # 断点续传已存在就跳过 with session.get(url, headersheaders, streamTrue, timeout60) as r: r.raise_for_status() with open(save_path, wb) as f: for chunk in r.iter_content(chunk_size8192): f.write(chunk) return done逻辑说明safe_filename把非法字符替换成下划线压缩连续空白超长时保留扩展名截断主体。download_file用streamTrue流式下载避免大文件一次性读进内存os.path.exists判断实现最简单的断点续传——已下载的非空文件直接跳过重跑时不会重复下载。参数上chunk_size8192是通用值网络差可以调小本地快可以调大到 65536。timeout60防止某个请求卡死拖垮整个任务。目录结构建议按「课程名/内容区名/文件名」组织这样下载完打开就是清晰的课程归档而不是一堆散文件。课程名从课程页标题提取内容区名从文件夹链接文字提取同样要过一遍safe_filename。3.4 限速与重试别把学校服务器打挂批量下载几十上百个文件如果不加控制很容易触发服务器限流甚至被封 IP。加个简单限速和重试。import time from requests.adapters import HTTPAdapter from urllib3.util.retry import Retry def build_session(): session requests.Session() retry Retry(total3, backoff_factor1.5, status_forcelist[429, 500, 502, 503, 504]) session.mount(https://, HTTPAdapter(max_retriesretry)) return session # 每个文件下载之间 sleep控制节奏 for f in all_files: download_file(session, f[url], path, headers) time.sleep(1.0) # 每秒一个按需调整逻辑说明Retry对 429限流和 5xx 错误自动重试backoff_factor1.5让重试间隔指数增长避免密集重试。time.sleep(1.0)是主动限速1 秒一个文件对几百个文件来说也就几分钟但能大幅降低被封风险。参数上如果文件特别多可以调到 0.5 秒如果服务器响应慢反而要调大避免堆积。4. 避坑与排查那些让我重跑整晚的坑这一章全是踩过的坑每条按「现象 → 原因 → 解决」写照着排查能省你几个通宵。4.1 下载下来的全是登录页 HTML现象文件下下来了但打开一看是登录页的 HTML大小都差不多几百字节。原因Cookie 过期或没带上请求被重定向到登录页而你的代码把重定向后的 HTML 当文件存了。解决下载前先做一次登录态验证见 2.2 的代码并且在download_file里检查Content-Type如果是text/html且文件本该是 PDF/PPT就报警而不是落盘。4.2 文件夹递归到一半就停了现象顶层文件下完了子文件夹里的一个都没有。原因Blackboard 的文件夹展开是 AJAX静态请求课程主页拿不到子层内容或者content_id提取错了。解决确认文件夹链接确实带content_id并且请求的是listContent.jsp而不是主页必要时用浏览器开发者工具的 Network 面板看点击文件夹时实际发了什么请求照着构造。4.3 文件名乱码或变成一串百分号编码现象下载的文件名是%E8%AF%BE%E7%A8%8B.pdf这种。原因链接文字或 URL 里的中文没做 URL 解码。解决对文件名用urllib.parse.unquote()解码再走safe_filename清洗。如果服务器返回的Content-Disposition头里有文件名优先用它比链接文字准。4.4 跑到一半 Cookie 失效后面全失败现象前几十个文件正常后面全是登录页。原因会话 Cookie 有有效期批量任务跑太久就过期了。解决在下载循环里定期比如每 20 个文件做一次登录态检查失效就暂停并提示重新导出 Cookie或者把任务拆成小批次每批重新验证。4.5 重名文件互相覆盖现象同一门课里两个不同文件夹有同名文件下载完只剩一个。原因落盘路径没带足够的层级信息或者同名直接覆盖。解决目录结构带上内容区名路径形如课程/内容区/文件名如果同一层还有重名在文件名后追加短哈希或序号。5. 进阶让下载器更省心、更可验证的几个技巧基础版跑通后可以往上加几个提升体验的东西。第一个是增量同步把已下载文件的 URL 或content_id记到一个本地 JSON 里下次跑只下新增的。这样每周跑一次就能保持课程资料最新不用全量重下。实现上就是在download_file前查一下记录下载成功后写回。第二个是并发下载。单线程一秒一个文件几百个文件要十几分钟。用concurrent.futures.ThreadPoolExecutor开 3 到 5 个线程并发速度能提升几倍但别开太多否则容易触发限流。配合前面的重试机制稳定性也够。from concurrent.futures import ThreadPoolExecutor def download_task(f): download_file(session, f[url], build_path(f), headers) return f[name] with ThreadPoolExecutor(max_workers4) as pool: results list(pool.map(download_task, all_files)) print(f完成 {len(results)} 个文件)参数上max_workers4是保守值学校服务器扛得住可以到 8但一定要配合重试和限速否则并发越高越容易被封。第三个是验证下载完整性。跑完后统计一下预期文件数 vs 实际落盘数总大小是否合理有没有 0 字节文件。写个简单的校验脚本比人眼翻目录靠谱得多。校验项判断方法异常处理文件数对比解析出的链接数少了就查日志找失败项文件大小检查 0 字节文件重新下载该文件文件类型检查扩展名与 Content-Type不符则可能是登录页最后一个技巧是把配置外置。域名、Cookie、课程 ID、保存路径、限速参数全写到一个config.yaml或环境变量里代码不动换学校换学期只改配置。这样这套东西能跟着你从一门课用到毕业甚至分享给同学时他们只改自己的 Cookie 就行。我自己现在的习惯是每学期开学跑一次全量之后每周跑一次增量配置和 Cookie 单独存代码基本不动。踩过的坑大多集中在登录态和文件名上把这两块做扎实剩下的就是耐心等它跑完。希望帮到你。本文还有配套的精品资源点击获取