Data-Science-For-Beginners 故障排查实战指南：从 Python 环境、Jupyter 到 quiz-app 与 Docsify 的完整排错手册

本文围绕 Data-Science-For-Beginners 课程的官方故障排查文档（TROUBLESHOOTING.md，另见英文原版 TROUBLESHOOTING.md）展开，系统讲解学习该课程时最可能遇到的九类问题：Python 与 Jupyter 环境、pip 依赖安装、Notebook 运行与绘图、quiz-app 测验应用、Git/GitHub 操作、Docsify 文档站点、数据文件读取、性能优化以及求助规范。读完并对照仓库中真实的 quiz-app/package.json、index.html 等文件核验后，你将能够独立完成从环境搭建到本地运行课程文档站点的全链路排错。

一、Python 与 Jupyter 环境问题

Python 未安装或版本错误

现象： 终端报 python: command not found，或 python --version 显示的版本不符合预期。

排查与解决（macOS/Linux）：

# 确认两个命令各自的版本
python --version
python3 --version

# 如果系统只安装了 python3，可建立别名
# 在 ~/.bashrc 或 ~/.zshrc 中加入：
alias python=python3
alias pip=pip3

# 或者显式使用 python3 模块方式安装，避免 PATH 歧义
python3 -m pip install jupyter

Windows 解决路径： 重新安装 Python 并在安装向导中勾选 "Add Python to PATH"，然后重启终端。Windows 上最常见的“找不到命令”问题几乎都是漏勾这个选项导致的。

虚拟环境无法激活

这是跨平台差异最大的一类问题，需要分别处理：

Windows（执行策略拦截）：

# 遇到 execution policy 报错时，先放宽当前用户的执行策略
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# 再激活
venv\Scripts\activate

macOS/Linux（activate 脚本无执行权限）：

# 确保 activate 脚本可执行
chmod +x venv/bin/activate

# 再激活
source venv/bin/activate

验证是否真正激活：

# 提示符前应出现 (venv)
# 确认解释器指向虚拟环境
which python   # 应输出 venv 目录下的 python

Jupyter Kernel 异常

现象： "Kernel not found" 或 "Kernel keeps dying"（内核反复掉线）。

# 重新安装内核（注册一个自定义显示名）
python -m ipykernel install --user --name=datascience --display-name="Python (Data Science)"

# 或者退回默认内核
python -m ipykernel install --user

# 重启 Jupyter
jupyter notebook

现象： Jupyter 里显示的 Python 版本不对（用了系统 Python 而不是虚拟环境的）。

# 先激活虚拟环境，再在其内部安装并注册内核
source venv/bin/activate
pip install jupyter ipykernel
python -m ipykernel install --user --name=venv --display-name="Python (venv)"

# 然后在 Jupyter 菜单 Kernel -> Change kernel -> Python (venv) 切换

从源码结构看，本仓库每节课的 Notebook 都依赖 pandas、numpy、matplotlib 等库（例如 3-Data-Visualization/09-visualization-quantities/solution/notebook.ipynb 中直接 pd.read_csv('../../../data/birds.csv')），如果 Kernel 注册在了错误的解释器下，这些单元格会集体报 ModuleNotFoundError，因此“先激活环境、再装内核”的顺序至关重要。

二、包与依赖问题

导入错误（ModuleNotFoundError）

# 确认虚拟环境已激活
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__)"

pip 安装失败

权限错误：

# 用 --user 装到用户目录
pip install --user package-name

# 或者（推荐）在虚拟环境内安装，从根本上避开系统目录权限
python -m venv venv
source venv/bin/activate
pip install package-name

SSL 证书错误：

# 先升级 pip，新版通常能修复证书链问题
python -m pip install --upgrade pip

# 临时绕过：指定可信主机
pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name

包版本冲突

最稳妥的办法是放弃旧环境、重建全新虚拟环境，而不是逐个卸载修复：

python -m venv venv-new
source venv-new/bin/activate   # Windows: venv-new\Scripts\activate

# 需要固定版本时显式指定
pip install pandas==1.3.0
pip install numpy==1.21.0

# 或让 pip 自己解析依赖
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

三、Jupyter Notebook 运行问题

Jupyter 无法启动

# 安装
pip install jupyter

# 用模块方式启动，可绕开 PATH 中找不到 jupyter 命令的问题
python -m jupyter notebook

# 若装到了用户目录，把 ~/.local/bin 加入 PATH（macOS/Linux）
export PATH="$HOME/.local/bin:$PATH"

Notebook 无法加载或保存

1. 检查文件写权限：

ls -l notebook.ipynb      # 确认有写权限
chmod 644 notebook.ipynb # 必要时修正

2. 检查文件是否损坏：.ipynb 本质是 JSON，可用文本编辑器打开检查结构是否完整；损坏时把内容复制进新建 Notebook。
3. 清理 Jupyter 缓存：

jupyter notebook --clear-cache

单元格卡死（In [*]）

1. 中断内核：点击 "Interrupt" 按钮，或按键盘 I, I；
2. 重启内核：Kernel 菜单 → Restart；
3. 检查代码中的死循环；
4. 清空输出：Cell → All Output → Clear，避免超长输出拖慢页面。

matplotlib 图像不显示

# 在 Notebook 顶部加入内联魔法命令
%matplotlib inline

import matplotlib.pyplot as plt

plt.plot([1, 2, 3, 4])
plt.show()   # 务必调用 show()

交互式绘图可改用 %matplotlib notebook 或 %matplotlib widget。本仓库大量绘图练习（如 3-Data-Visualization/10-visualization-distributions/notebook.ipynb 的直方图与密度图）都依赖该内联机制，缺少 %matplotlib inline 时图形只会输出文本而不渲染。

四、quiz-app 测验应用问题

本仓库的测验应用位于 quiz-app，是一个 Vue 2 项目。从 quiz-app/package.json 可以确认：它基于 @vue/cli-service ~4.5.0、vue ^2.6.11、eslint ^6.7.2 构建，脚本为 serve（开发服务器）、build（生产构建）、lint（代码检查）。vue-cli 4.x 这一代工具链对 Node.js 的版本要求不高（12.x 以上即可），这也是官方文档中建议 node --version 不低于 12.x 的依据。

npm install 失败

# 清缓存
npm cache clean --force

# 删除依赖与锁文件后重装
rm -rf node_modules package-lock.json
npm install

# 仍失败时尝试忽略新版 peer 依赖校验
npm install --legacy-peer-deps

应用无法启动（npm run serve 失败）

node --version   # 应为 12.x 或更高

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 8081

页面空白

1. 按 F12 打开浏览器控制台查看报错；
2. 清理浏览器缓存与 Cookie；
3. 换一个浏览器；
4. 确认 JavaScript 已启用；
5. 检查广告拦截插件是否干扰。

# 重新构建后再启动
npm run build
npm run serve

从源码结构看，quiz-app/public/routes.json 将所有路由 /* 回退到 /index.html，这是 SPA 的常规配置；若构建产物不完整（如 npm run build 中途失败），刷新深层路由时就会出现白屏，因此“重新 build + serve”是有效的兜底手段。

五、Git 与 GitHub 问题

git 命令不存在

• Windows：从 Git 官网安装后重启终端；
• macOS：

# 通过 Homebrew 安装（未装 Homebrew 需先按其官网指引安装）
brew install git

# 或安装 Xcode 命令行工具（自带 git）
xcode-select --install

• Linux：

sudo apt-get install git   # Debian/Ubuntu
sudo dnf install git      # Fedora

git clone 认证失败

# 使用 HTTPS 地址克隆仓库
git clone https://github.com/microsoft/Data-Science-For-Beginners.git

# 若 GitHub 开启了 2FA：在 GitHub 的 Personal Access Tokens 设置页
# 创建一个 Token，克隆提示输入密码时使用 Token 代替密码

SSH 公钥被拒（Permission denied (publickey)）

# 生成 ed25519 密钥
ssh-keygen -t ed25519 -C "[e-mail]"

# 启动 agent 并加载私钥
eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519

# 将公钥内容添加到 GitHub 的 SSH keys 设置页
# 查看公钥：cat ~/.ssh/id_ed25519.pub

六、Docsify 文档站点问题

本仓库的在线文档就是一个 Docsify 站点：入口 index.html 通过 CDN 加载 docsify，并在 window.$docsify 中配置了 name、repo 与 relativePath: true——relativePath: true 意味着所有 Markdown 内的图片、链接都按“相对当前文档”解析，这正是后面“图片不显示”问题的技术根源。侧边栏内容来自 docs/_sidebar.md。

docsify 命令不存在

# 全局安装 docsify-cli
npm install -g docsify-cli

# macOS/Linux 权限不足时
sudo npm install -g docsify-cli

# 验证
docsify --version

# 仍找不到时，查 npm 全局前缀并加入 PATH
npm config get prefix
export PATH="$PATH:/usr/local/bin"   # 写入 ~/.bashrc 或 ~/.zshrc

文档内容加载不出来

# 必须在仓库根目录（index.html 所在目录）启动
cd Data-Science-For-Beginners

# 确认入口文件存在
ls index.html

# 指定端口启动
docsify serve --port 3000

# 打开浏览器控制台（F12）查看加载报错

注意：仓库根目录另有 package.json 与 docsifytopdf.js，其 convert 脚本（node_modules/.bin/docsify-to-pdf）和 contents: ['docs/_sidebar.md'] 配置说明该目录也被用作 PDF 导出的工作目录——npm install 装的是 docsify-to-pdf 这类工具链依赖，与 quiz-app 的 node_modules 相互独立，排查 npm 问题时不要混淆两个目录。

图片显示为破损链接

1. 检查图片路径是否为相对路径（Docsify 已开启 relativePath）；
2. 确认图片文件确实存在于仓库对应目录；
3. 清理浏览器缓存；
4. 核对扩展名大小写是否一致（部分系统文件系统区分大小写）。

七、数据与文件问题

FileNotFoundError

课程各节 Notebook 通常放在三级子目录（如 3-Data-Visualization/09-visualization-quantities/），因此读取根目录 data/ 下的文件时需要 ../ 回退。仓库中真实用例可印证这一点，例如 3-Data-Visualization/09-visualization-quantities/solution/notebook.ipynb 使用 pd.read_csv('../../../data/birds.csv')。

import os

# 1. 先看当前工作目录到底在哪里
print(os.getcwd())

# 2. 用绝对路径拼接，避免相对路径歧义
data_path = os.path.join(os.getcwd(), 'data', 'filename.csv')
df = pd.read_csv(data_path)

# 3. 或者用相对路径（相对于 Notebook 所在位置）
df = pd.read_csv('../data/filename.csv')

# 4. 读之前先验证文件存在
print(os.path.exists('data/filename.csv'))

仓库实际提供的数据集见 data 目录：birds.csv、mushrooms.csv、honey.csv、taxi.csv、emails.csv、form.csv 等，以及 data/COVID 下的三个疫情时间序列 CSV。

CSV 读取错误

import pandas as pd

# 逐一尝试不同编码
df = pd.read_csv('file.csv', encoding='utf-8')
# 或
df = pd.read_csv('file.csv', encoding='latin-1')
# 或
df = pd.read_csv('file.csv', encoding='ISO-8859-1')

# 显式声明缺失值标记
df = pd.read_csv('file.csv', na_values=['NA', 'N/A', ''])

# 分隔符不是逗号时显式指定
df = pd.read_csv('file.csv', delimiter=';')

结合仓库数据可以补充一条原文档未展开的实操细节：data 目录下 SOCR_MLB.tsv 与 diabetes.tsv 是制表符分隔的 TSV 文件，读取时应使用 pd.read_csv('diabetes.tsv', sep='\t')，否则整行会被塞进单个字段。

大数据集内存不足（MemoryError）

# 分块读取
chunk_size = 10000
chunks = []
for chunk in pd.read_csv('large_file.csv', chunksize=chunk_size):
    chunks.append(chunk)
df = pd.concat(chunks)

# 只读需要的列
df = pd.read_csv('file.csv', usecols=['col1', 'col2'])

# 使用更紧凑的数据类型
df = pd.read_csv('file.csv', dtype={'column_name': 'int32'})

八、性能问题

Notebook 运行缓慢

1. 重启内核并清空输出：Kernel → Restart & Clear Output；
2. 关闭不用的 Notebook；
3. 用向量化操作替代 Python 循环：

# Bad：逐元素循环
result = []
for x in data:
    result.append(x * 2)

# Good：NumPy/Pandas 向量化
result = data * 2

4. 开发阶段对大表采样：

df_sample = df.sample(n=1000)   # 或 df.head(1000)

浏览器崩溃或无响应

1. 关闭无关标签页；
2. 清理浏览器缓存；
3. 提高浏览器内存上限（Chrome 可在 chrome://settings/system 调整）；
4. 换用 JupyterLab：

pip install jupyterlab
jupyter lab

九、获取进一步帮助

求助前的自检清单

1. 先查这份排查指南；
2. 在 GitHub Issues 中搜索同类报错；
3. 回顾 INSTALLATION.md 与 USAGE.md；
4. 直接搜索完整报错文本。

求助时务必包含的信息

1. 操作系统：Windows / macOS / Linux（发行版）；
2. Python 版本：运行 python --version 的结果；
3. 完整报错信息；
4. 复现步骤：出错前做了什么；
5. 已尝试的方案。

示例格式：

**Operating System:** macOS 12.0
**Python Version:** 3.9.7
**Error Message:** ModuleNotFoundError: No module named 'pandas'
**Steps to Reproduce:**
1. Activated virtual environment
2. Started Jupyter notebook
3. Tried to import pandas

**What I've Tried:**
- Ran pip install pandas
- Restarted Jupyter

相关文档

• INSTALLATION.md：环境安装步骤；
• USAGE.md：课程使用方法；
• CONTRIBUTING.md：贡献规范；
• README.md：课程总览。

适用范围说明

本文中的命令与版本建议以当前仓库实际内容为准：quiz-app 基于 Vue 2 + vue-cli 4.x（见 quiz-app/package.json），Node.js 建议 12.x 以上；课程核心 Python 栈为 jupyter pandas numpy matplotlib seaborn scikit-learn。各节 Notebook 对数据路径的引用方式（如 ../../../data/...）取决于你打开 Notebook 的具体目录层级，遇到 FileNotFoundError 时请先用 os.getcwd() 确认工作目录，再修正相对路径。