Data-Science-For-Beginners 排障实战手册从 Python 环境到 Quiz 应用与 Docsify 的完整问题解决方案【免费下载链接】Data-Science-For-Beginners10 Weeks, 20 Lessons, Data Science for All!项目地址: https://gitcode.com/GitHub_Trending/da/Data-Science-For-Beginners本手册以开源课程 Data-Science-For-Beginners 仓库中的 TROUBLESHOOTING.md 为骨架系统梳理了学习与二次开发过程中最常遇到的 8 大类故障——Python/Jupyter 环境、依赖安装、Notebook 运行、Quiz 测验应用、Git 操作、Docsify 文档站点、数据文件读写与性能问题。读完本文你将掌握一套问题定位 → 修复命令 → 验证结果的标准排障流程能独立解决从搭建环境到运行 quiz-app 测验应用、从读取 data 目录数据集到本地部署 Docsify 文档的全链路问题。排障前先理解环境组成Data-Science-For-Beginners 课程由三套相对独立的技术栈组成绝大多数故障都发生在它们的边界处技术栈用途仓库中的关键文件Python 3 Jupyter运行 20 节课的.ipynb笔记本与数据练习1-Introduction 至 6-Data-Science-In-Wild 各课目录中的notebook.ipynbNode.js Vue 2运行课前/课后测验应用40 道测验quiz-app/package.json、quiz-app/src/main.jsDocsify将课程 README 渲染为本地离线文档站点index.html、docs/_sidebar.md正式排障前建议先阅读 INSTALLATION.md环境搭建步骤与 USAGE.md课程使用流程确认基础环境是否完整。以下各节按症状 → 原因 → 修复的结构展开。Python 与 Jupyter 环境问题Python 未找到或版本不对症状执行python报python: command not found或python --version显示的版本与预期不符。修复步骤# 检查 Python 版本 python --version python3 --version多数 Linux 发行版与 macOS 自带的是python3而非python。若确认 Python 3 已安装可通过别名统一命令macOS/Linux 下写入~/.bashrc或~/.zshrcalias pythonpython3 alias pippip3也可以跳过别名直接用python3显式调用python3 -m pip install jupyterWindows 环境重新从 python.org 安装 Python 时务必勾选Add Python to PATH安装完成后重启终端使 PATH 生效。注意 INSTALLATION.md 明确要求Python 3.7 及以上版本低于该版本的部分课程依赖如新版 pandas 特性将无法正常工作。虚拟环境无法激活症状运行激活命令无反应或报错后环境未生效。WindowsPowerShell执行策略限制# 若提示执行策略错误 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # 然后激活 venv\Scripts\activatemacOS/Linux 激活脚本无执行权限# 确保 activate 脚本可执行 chmod x venv/bin/activate # 然后激活 source venv/bin/activate验证是否激活成功# 激活后命令行提示符应显示 (venv) which python # 应指向虚拟环境内的解释器如果which python仍指向系统 Python说明虚拟环境未创建成功可重新执行python -m venv venv创建。Jupyter 内核问题症状打开笔记本提示 Kernel not found或运行代码时 Kernel keeps dying内核反复崩溃。修复方式重新注册 ipykernel 内核# 注册自定义内核 python -m ipykernel install --user --namedatascience --display-namePython (Data Science) # 或使用默认内核 python -m ipykernel install --user # 重启 Jupyter jupyter notebook症状Jupyter 中使用的是系统 Python 而非虚拟环境中的 Python导致虚拟环境里装的包在 Jupyter 里 import 不到。修复方式在虚拟环境中重新安装 Jupyter 并注册内核source venv/bin/activate # 先激活虚拟环境 pip install jupyter ipykernel # 注册内核 python -m ipykernel install --user --namevenv --display-namePython (venv) # 在 Jupyter 中Kernel - Change kernel - Python (venv)这一节是课程学习中最常见的坑内核与虚拟环境绑定错误本质是 ipykernel 注册到了错误的解释器上上述命令确保内核指向虚拟环境内的 Python。包与依赖问题Import 错误症状ModuleNotFoundError: No module named pandas或其他包名。修复先确认虚拟环境已激活再安装缺失包source venv/bin/activate # macOS/Linux venv\Scripts\activate # Windows # 安装单个缺失包 pip install pandas # 或一次性安装本课程常用全家桶 pip install jupyter pandas numpy matplotlib seaborn scikit-learn # 验证安装 python -c import pandas; print(pandas.__version__)以仓库中的示例脚本为参照examples/02_loading_data.py 顶部就注明pip install pandas是运行前置条件examples/03_simple_analysis.py 与 examples/04_basic_visualization.py 则额外依赖 matplotlib。逐课练习时可参照各课notebook.ipynb顶部 import 清单补齐包。pip 安装失败权限错误Permission denied优先用--user安装到当前用户目录pip install --user package-name更推荐的做法是始终使用虚拟环境避免污染系统 Pythonpython -m venv venv source venv/bin/activate pip install package-nameSSL 证书错误先升级 pip 本身再考虑临时信任主机python -m pip install --upgrade pip # 临时绕行方案仅在网络代理/内网环境必要时使用 pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name包版本冲突症状安装 A 包时提示与已装的 B 包版本不兼容。修复推荐创建全新的虚拟环境避免历史残留版本干扰python -m venv venv-new source venv-new/bin/activate # Windows 下为 venv-new\Scripts\activate # 指定版本安装 pip install pandas1.3.0 pip install numpy1.21.0 # 或让 pip 自动解析依赖 pip install jupyter pandas numpy matplotlib seaborn scikit-learn注意仓库 INSTALLATION.md 建议使用python -m venv venv创建隔离环境排障时的重建环境策略正是基于这一实践——当依赖关系已不可控时从干净环境重新安装往往比逐包排查更快。Jupyter Notebook 问题Jupyter 无法启动症状jupyter notebook报command not found。修复# 安装 Jupyter pip install jupyter # 或使用 python -m 调用 python -m jupyter notebook # 若仍未找到命令将用户安装目录加入 PATHmacOS/Linux export PATH$HOME/.local/bin:$PATHNotebook 无法加载或保存按以下顺序排查检查文件权限——确保对.ipynb文件有写权限ls -l notebook.ipynb chmod 644 notebook.ipynb # 如需要检查文件是否损坏——.ipynb本质是 JSON 结构可用文本编辑器打开确认 JSON 是否完整若已损坏可将可读部分内容复制到新笔记本中。清理 Jupyter 缓存jupyter notebook --clear-cache单元格无法执行症状单元格一直停留在In [*]状态或执行超时。按序处理中断内核点击 Interrupt 按钮或连按两次I键重启内核Kernel 菜单 → Restart检查代码中的死循环最常见于while循环条件恒真清理输出Cell → All Output → Clear绘图不显示症状matplotlib 绘制的图表在笔记本中不渲染。修复在笔记本顶部添加%matplotlib inline魔法命令并显式调用plt.show()%matplotlib inline import matplotlib.pyplot as plt # 创建图表 plt.plot([1, 2, 3, 4]) plt.show() # 务必调用 show()交互式图表的替代方案%matplotlib notebook # 或 %matplotlib widget课程中第 913 课3-Data-Visualization大量使用 matplotlib 绘图若某个可视化图表不显示优先检查这两处magic 命令是否置于 import 之前、是否调用了plt.show()。Quiz 测验应用问题Quiz 应用是基于 Vue 2 的前端工程入口配置见 quiz-app/package.json依赖vue^2.6.11、vue-router^3.4.9、vue-i18n^8.22.2开发服务器由vue/cli-service提供。npm install 失败修复# 清理 npm 缓存 npm cache clean --force # 移除 node_modules 与锁文件后重装 rm -rf node_modules package-lock.json npm install # 若仍失败尝试 legacy peer deps 模式 npm install --legacy-peer-deps从 quiz-app/package.json 可以看到工程使用较旧的 Vue CLI 4.5 工具链vue/cli-service: ~4.5.0、eslint: ^6.7.2在与新版本 npm 的 peerDependencies 校验冲突时--legacy-peer-deps通常是有效兜底。Quiz 应用无法启动症状npm run serve报错。修复# 检查 Node.js 版本应不低于 12.x node --version # 重新安装依赖 cd quiz-app rm -rf node_modules package-lock.json npm install # 换端口启动 npm run serve -- --port 8081端口已被占用症状报 Port 8080 is already in use。修复# macOS/Linux查找并结束占用 8080 端口的进程 lsof -ti:8080 | xargs kill -9 # Windows netstat -ano | findstr :8080 taskkill /PID PID /F # 或直接换端口 npm run serve -- --port 8081Quiz 加载后空白页症状应用打开但页面空白。按序排查打开浏览器开发者工具F12查看 Console 报错清理浏览器缓存与 Cookie换一个浏览器尝试确认浏览器启用了 JavaScript检查广告拦截插件是否误拦截然后重新构建并启动npm run build npm run serve从 quiz-app/src/router/index.js 的源码看应用采用 history 路由模式路由表包含首页/、测验页/quiz/:id以及兜底的NotFound组件——若npm run serve后访问的路径无法匹配这组路由会直接落入 404 视图这也可以解释空白页的另一类成因。Git 与 GitHub 问题git 未识别症状git: command not found。按平台安装Windows从 git-scm.com 下载安装安装后重启终端macOS先安装 Homebrew再执行brew install git # 或安装 Xcode Command Line Tools xcode-select --installLinuxsudo apt-get install git # Debian/Ubuntu sudo dnf install git # Fedoragit clone 失败症状克隆时出现认证错误。修复使用 HTTPS 方式克隆启用两步验证2FA的账号需使用 Personal Access Token 代替密码git clone https://github.com/microsoft/Data-Science-For-Beginners.git在提示输入密码时粘贴 Token 即可完成认证。Permission Denied (publickey)症状SSH 方式认证失败。修复重新生成 SSH 密钥并注册到 GitHub# 生成 ed25519 密钥 ssh-keygen -t ed25519 -C your_emailexample.com # 将密钥加入 ssh-agent eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 # 查看公钥内容并粘贴到 GitHub 设置页的 SSH Keys 中 cat ~/.ssh/id_ed25519.pubDocsify 文档问题docsify 命令未找到修复# 全局安装 docsify-cli npm install -g docsify-cli # macOS/Linux 下若权限不足 sudo npm install -g docsify-cli # 验证安装 docsify --version # 仍未找到时将 npm 全局路径加入 PATH npm config get prefix # 查看 npm 全局安装路径 export PATH$PATH:/usr/local/bin # 写入 ~/.bashrc 或 ~/.zshrc文档加载不出来修复# 确认位于仓库根目录 cd Data-Science-For-Beginners # 确认 index.html 存在 ls index.html # 指定端口启动 docsify serve --port 3000 # 若内容仍空白打开浏览器开发者工具F12查看报错仓库根目录的 index.html 是 Docsify 的入口它通过 CDN 加载docsify.min.js并配置了relativePath: true以支持仓库内相对路径跳转文档侧边栏结构则由 docs/_sidebar.md 定义覆盖第 120 课全部章节。若离线或无外网环境CDN 无法加载会直接导致页面空白此时需保证网络连通或改用本地托管方式。图片不显示症状页面图片显示为破图图标。排查清单确认图片路径为相对路径仓库内图片统一放在各课images/目录与根级 images、sketchnotes、translated_images 目录确认图片文件确实存在于仓库中清理浏览器缓存确认文件扩展名大小写一致部分系统对大小写敏感数据与文件问题文件找不到症状加载数据时抛FileNotFoundError。修复先确认当前工作目录再使用绝对或相对路径import os # 检查当前工作目录 print(os.getcwd()) # 使用绝对路径 data_path os.path.join(os.getcwd(), data, filename.csv) df pd.read_csv(data_path) # 或从笔记本所在目录向上引用 df pd.read_csv(../data/filename.csv) # 验证文件是否存在 print(os.path.exists(data/filename.csv))仓库 data 目录内置了全部课程数据集如birds.csv、honey.csv、mushrooms.csv、diabetes.tsv等示例脚本 examples/02_loading_data.py 与 examples/05_real_world_example.py 均采用pd.read_csv(../data/birds.csv)这种从examples/目录向上引用的写法——保持这种目录相对关系是避免 FileNotFoundError 的关键。CSV 读取错误症状读取 CSV 时报编码或解析错误。修复依次尝试编码、缺失值、分隔符参数import pandas as pd # 尝试不同编码 df pd.read_csv(file.csv, encodingutf-8) # 或 df pd.read_csv(file.csv, encodinglatin-1) # 或 df pd.read_csv(file.csv, encodingISO-8859-1) # 指定缺失值标记 df pd.read_csv(file.csv, na_values[NA, N/A, ]) # 指定分隔符非逗号时 df pd.read_csv(file.csv, delimiter;)大数据集内存不足症状加载大文件时抛MemoryError。修复分块读取、按需取列、降精度# 分块读取 chunk_size 10000 chunks [] for chunk in pd.read_csv(large_file.csv, chunksizechunk_size): # 处理每个分块 chunks.append(chunk) df pd.concat(chunks) # 只读取需要的列 df pd.read_csv(file.csv, usecols[col1, col2]) # 使用更高效的数据类型如 int32 而非 int64 df pd.read_csv(file.csv, dtype{column_name: int32})性能问题Notebook 运行缓慢按序优化重启内核并清空输出Kernel → Restart Clear Output关闭不用的笔记本多个活跃内核会竞争内存用向量化运算替代循环# 不推荐逐元素循环 result [] for x in data: result.append(x * 2) # 推荐NumPy/Pandas 向量化 result data * 2开发阶段先抽样# 开发时用样本子集 df_sample df.sample(n1000) # 或 df.head(1000)浏览器崩溃或无响应关闭多余标签页清理浏览器缓存增大浏览器可用内存Chromechrome://settings/system改用 JupyterLab 替代pip install jupyterlab jupyter lab高效求助把问题描述清楚求助前的自查清单在向他人提问之前按顺序完成通读本排障手册即 TROUBLESHOOTING.md确认覆盖的 8 大类问题是否包含你的场景搜索课程仓库的 Issues 区看是否已有相同问题复查 INSTALLATION.md环境搭建与 USAGE.md使用流程用搜索引擎检索完整报错信息提问时需提供的信息创建 Issue 或求助时务必包含以下 5 项信息缺一不可操作系统Windows / macOS / Linux注明发行版Python 版本运行python --version完整错误信息复制整段报错而非只描述现象复现步骤出错前依次做了什么已尝试的解法尝试过哪些修复、结果如何提问示例**操作系统** macOS 12.0 **Python 版本** 3.9.7 **错误信息** ModuleNotFoundError: No module named pandas **复现步骤** 1. 激活了虚拟环境 2. 启动 Jupyter notebook 3. 尝试 import pandas **已尝试** - 执行了 pip install pandas - 重启了 Jupyter仓库内相关文档导航排障时可交叉查阅以下仓库文档INSTALLATION.md —— 从零搭建环境的完整步骤Git、Python、Node.js、Docsify、VS Code Dev ContainersUSAGE.md —— 课程使用流程与常见工作流自学、课堂教学、离线使用、多语言内容访问CONTRIBUTING.md —— 如何提交 Issue 或参与贡献README.md —— 课程总览与章节地图小结一套可复用的排障方法论回顾本手册Data-Science-For-Beginners 课程的排障可以沉淀为三条通用原则环境隔离优先所有 Python 依赖一律装入虚拟环境python -m venv venv遇到版本冲突直接重建环境而不是在系统环境里反复修补Jupyter 必须通过 ipykernel 与虚拟环境内核绑定。前端双栈分治Quiz 应用Node/Vue与 Docsify 文档npm 全局工具是两个独立的 npm 生态故障互不相干——先确认node --version与npm config get prefix再决定是重建node_modules还是补全 PATH。数据路径相对化所有课程示例统一采用以data/目录为基准的相对路径如 examples/05_real_world_example.py 中的../data/birds.csv保持这一约定即可避免绝大多数 FileNotFoundError。掌握以上方法后无论遇到 Python 环境、依赖冲突、Notebook 内核、Quiz 应用、Docsify 站点还是数据集问题你都能按照定位环境 → 隔离修复 → 验证运行的路径独立解决把精力重新放回 20 节课程本身的数据科学学习上。【免费下载链接】Data-Science-For-Beginners10 Weeks, 20 Lessons, Data Science for All!项目地址: https://gitcode.com/GitHub_Trending/da/Data-Science-For-Beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考