Data Science for Beginners 排障实战指南Python、Jupyter、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 Beginners10 周、20 课覆盖数据科学入门到实战的 TROUBLESHOOTING.md本仓库根目录英文原版及 translations/el/TROUBLESHOOTING.md 等 40 语言译本展开系统梳理学习者在安装、运行课程 Notebook、启动 Quiz 测验应用与 Docsify 文档站点时最常遇到的八大类问题。读完本文你将掌握从 Python 版本错乱、虚拟环境失效、Kernel 崩溃到 npm 依赖冲突、端口占用、Git 认证失败、CSV 编码与大数据内存溢出的完整排查命令与代码级修复方案并学会撰写一份高质量的问题报告以快速获得社区帮助。问题速查总览课程日常学习涉及四套独立工具链Python/Jupyter执行课程 Notebook、npm/Vue运行 quiz-app 测验应用、Git/GitHub拉取与同步仓库、Docsify本地文档服务。按故障域划分本指南覆盖以下内容故障域典型症状涉及仓库资源Python 与 Jupyterpython: command not found、版本不符、虚拟环境无法激活、Kernel 丢失/崩溃INSTALLATION.md 第 3~5 步包与依赖ModuleNotFoundError、pip 权限/SSL 失败、版本冲突INSTALLATION.md 第 5 步Jupyter Notebook命令找不到、无法加载/保存、单元格卡死、图表不显示各课notebook.ipynb如 04-stats-and-probability/notebook.ipynbQuiz 应用npm install 失败、npm run serve失败、8080 端口占用、空白页quiz-app/package.json、quiz-app/public/routes.jsonGit 与 GitHubgit 未安装、clone 认证失败、SSH publickey 被拒INSTALLATION.md 第 1~2 步Docsify 文档docsify命令找不到、内容不加载、图片裂开index.html、docs/_sidebar.md数据与文件FileNotFoundError、CSV 读取出错、大文件MemoryErrordata 目录birds.csv、mushrooms.csv、honey.csv、taxi.csv等性能Notebook 运行缓慢、浏览器崩溃各课 Notebook 中的向量化示例Python 与 Jupyter 问题Python 未找到或版本错误症状python: command not found或python与python3指向不同版本导致后续安装错乱。解决方案先确认环境中实际可用的解释器# Check Python version python --version python3 --version如果 Python 3 仅以python3形式存在可在 macOS/Linux 的~/.bashrc或~/.zshrc中配置别名# If Python 3 is installed as python3, create an alias # On macOS/Linux, add to ~/.bashrc or ~/.zshrc: alias pythonpython3 alias pippip3或者干脆显式使用python3例如安装 Jupyter# Or use python3 explicitly python3 -m pip install jupyterWindows 方案从 python.org 重新安装 Python安装时务必勾选 Add Python to PATH重新打开终端/命令提示符使 PATH 生效。仓库佐证INSTALLATION.md 要求 Python 3.7 及以上版本并明确在 Windows 安装流程中强调勾选 Add Python to PATH。虚拟环境无法激活症状执行激活命令报错或激活后未生效。Windows常见为 PowerShell 执行策略限制# If you get execution policy error Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser # Then activate venv\Scripts\activatemacOS/Linux脚本不可执行或路径问题# Ensure the activate script is executable chmod x venv/bin/activate # Then activate source venv/bin/activate激活验证# Your prompt should show (venv) # Check Python location which python # Should point to venvwhich python输出应指向虚拟环境目录内的解释器例如/path/to/venv/bin/python而非系统全局路径这是判断激活是否成功的硬指标。Jupyter Kernel 问题症状Kernel not foundKernel 列表中没有可用内核或 Kernel keeps dying内核反复崩溃。解决方案重新安装/注册内核# Reinstall kernel python -m ipykernel install --user --namedatascience --display-namePython (Data Science) # Or use the default kernel python -m ipykernel install --user # Restart Jupyter jupyter notebook症状Jupyter 中运行代码用的 Python 版本与虚拟环境不一致导入已装的包却失败。解决方案在虚拟环境内安装并注册专属内核# Install Jupyter in your virtual environment source venv/bin/activate # Activate first pip install jupyter ipykernel # Register the kernel python -m ipykernel install --user --namevenv --display-namePython (venv) # In Jupyter, select Kernel - Change kernel - Python (venv)关键提示课程每个 Notebook 都应使用与安装依赖时相同的虚拟环境内核否则会出现包明明装了却ModuleNotFoundError的经典乌龙。可参考 2-Working-With-Data/07-python/notebook.ipynb 的导入语句核对依赖。包与依赖问题导入报错ModuleNotFoundError症状ModuleNotFoundError: No module named pandas或其他课程常用包如 numpy、matplotlib、seaborn、scikit-learn。解决方案确认虚拟环境已激活后安装缺失包# Ensure virtual environment is activated source venv/bin/activate # macOS/Linux venv\Scripts\activate # Windows # Install missing package pip install pandas # Install all common packages pip install jupyter pandas numpy matplotlib seaborn scikit-learn # Verify installation python -c import pandas; print(pandas.__version__)最后一行用 Python 直接验证安装结果能同时确认解释器正确 包已装到当前环境两个事实是排查导入类问题的标准收尾动作。pip 安装失败症状一pip install因权限不足失败多见于系统级 Python 环境。解决方案# Use --user flag pip install --user package-name # Or use virtual environment (recommended) python -m venv venv source venv/bin/activate pip install package-name症状二pip install报 SSL 证书错误常见于公司代理或受限网络。解决方案# Update pip first python -m pip install --upgrade pip # Try installing with trusted host (temporary workaround) pip install --trusted-host pypi.org --trusted-host files.pythonhosted.org package-name注意--trusted-host属于绕过证书校验的临时手段仅在信任的网络环境下使用升级 pip 后通常无需此参数。包版本冲突症状不同库依赖同一库的不同版本安装或运行时行为异常。解决方案重建一个干净的环境并按需锁定版本# Create fresh virtual environment python -m venv venv-new source venv-new/bin/activate # or venv-new\Scripts\activate on Windows # Install packages with specific versions if needed pip install pandas1.3.0 pip install numpy1.21.0 # Or let pip resolve dependencies pip install jupyter pandas numpy matplotlib seaborn scikit-learn当不确定具体版本组合时优先让 pip 自行解析依赖即最后一条命令锁定版本仅在你明确知道某个版本兼容时才使用。课程数据操作核心依赖是 pandas numpy见 3-Data-Visualization/09-visualization-quantities/notebook.ipynb 顶部导入块。Jupyter Notebook 问题Jupyter 无法启动症状jupyter notebook命令找不到。解决方案# Install Jupyter pip install jupyter # Or use python -m python -m jupyter notebook # Add to PATH if needed (macOS/Linux) export PATH$HOME/.local/bin:$PATHpython -m jupyter notebook这种调用方式不依赖 PATH只要解释器正确就能启动是排障时最可靠的兜底写法。Notebook 无法加载或保存症状Notebook failed to load 或保存时报错。解决步骤检查文件权限# Make sure you have write permissions ls -l notebook.ipynb chmod 644 notebook.ipynb # If needed检查文件是否损坏.ipynb本质是 JSON 结构可用文本编辑器打开检查结构损坏则复制内容到新 Notebook# Try opening in text editor to check JSON structure # Copy content to new notebook if corrupted清理 Jupyter 缓存jupyter notebook --clear-cache单元格无法执行症状单元格卡在In [*]状态或执行时间过长。解决方案中断内核点击工具栏 Interrupt 按钮或快捷键I, I重启内核Kernel 菜单 → Restart检查死循环检查代码中是否存在while True或无终止条件的循环清理输出Cell → All Output → Clear释放因超长输出导致的界面卡顿。图表不显示症状matplotlib绘制的图在 Notebook 内不渲染。解决方案在 Notebook 顶部加入魔法命令并显式调用show()# Add magic command at the top of notebook %matplotlib inline import matplotlib.pyplot as plt # Create plot plt.plot([1, 2, 3, 4]) plt.show() # Make sure to call show()需要交互式图表缩放、平移时可选%matplotlib notebook # Or %matplotlib widget课程各可视化课的 Notebook 大量使用 matplotlib 输出图表例如 3-Data-Visualization/09-visualization-quantities/notebook.ipynb 与 10-visualization-distributions/notebook.ipynb若图表空白优先检查本小节。Quiz 测验应用问题课程测验应用位于 quiz-app是基于 Vue 2 构建的前端项目。仓库内 quiz-app/package.json 声明了三个核心脚本serve开发服务器、build生产构建、lint代码检查主依赖为vue^2.6.11、vue-router^3.4.9、vue-i18n^8.22.2构建工具为vue/cli-service~4.5.0。npm install 失败症状执行npm install时出现依赖解析或网络错误。解决方案# Clear npm cache npm cache clean --force # Remove node_modules and package-lock.json rm -rf node_modules package-lock.json # Reinstall npm install # If still failing, try with legacy peer deps npm install --legacy-peer-deps--legacy-peer-deps可绕过新版 npm 严格的 peer 依赖检查在项目使用较老依赖树如本项目的 Vue CLI 4.x 生态时是有效的兼容开关。Quiz 应用无法启动症状npm run serve失败。解决方案# Check Node.js version node --version # Should be 12.x or higher # Reinstall dependencies cd quiz-app rm -rf node_modules package-lock.json npm install # Try different port npm run serve -- --port 8081注意npm run serve必须在 quiz-app 目录内执行该目录是 package.json 所在位置根目录的 package.json 仅提供convertdocsify 转 PDF脚本不包含 serve 命令。端口已被占用症状报 Port 8080 is already in use。解决方案# Find and kill process on port 8080 # macOS/Linux: lsof -ti:8080 | xargs kill -9 # Windows: netstat -ano | findstr :8080 taskkill /PID PID /F # Or use a different port npm run serve -- --port 8081Quiz 加载空白页症状应用能启动但页面空白。解决步骤打开浏览器控制台查看报错F12清理浏览器缓存与 Cookies换一个浏览器试试确认 JavaScript 已启用检查广告拦截插件是否干扰。然后重新构建并启动# Rebuild the app npm run build npm run serve补充该应用采用 SPA 路由quiz-app/public/routes.json 将所有路由回退到index.html。若部署在子路径或静态服务器未配置回退规则刷新深层路由可能出现空白/404这也是空白页的常见成因之一。Git 与 GitHub 问题Git 未被识别症状git: command not found。Windows从 git-scm.com 安装 Git 并重启终端。macOS若未安装 Homebrew先按其官网指引安装# Install via Homebrew brew install git # Or install Xcode Command Line Tools xcode-select --installLinuxsudo apt-get install git # Debian/Ubuntu sudo dnf install git # Fedora克隆失败症状git clone出现认证错误。解决方案# Use HTTPS URL git clone https://github.com/microsoft/Data-Science-For-Beginners.git # If you have 2FA enabled on GitHub, use Personal Access Token # Create token at: https://github.com/settings/tokens # Use token as password when prompted开启了两步验证2FA的账户HTTPS 克隆时的密码应替换为 Personal Access Token。权限被拒publickey症状SSH 方式认证失败报Permission denied (publickey)。解决方案# Generate SSH key ssh-keygen -t ed25519 -C your_emailexample.com # Add key to ssh-agent eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 # Add public key to GitHub # Copy key: cat ~/.ssh/id_ed25519.pub # Add at: https://github.com/settings/keys生成 ed25519 密钥后将公钥id_ed25519.pub内容添加到 GitHub 账户的 SSH keys 中即可。Docsify 文档问题课程文档通过 Docsify 渲染仓库根目录 index.html 中window.$docsify配置了文档名与relativePath: true支持相对路径链接侧边栏结构定义在 docs/_sidebar.md。docsify 命令未找到症状docsify: command not found。解决方案# Install globally npm install -g docsify-cli # If permission error on macOS/Linux sudo npm install -g docsify-cli # Verify installation docsify --version # If still not found, add npm global path # Find npm global path npm config get prefix # Add to PATH (add to ~/.bashrc or ~/.zshrc) export PATH$PATH:/usr/local/bin文档内容不加载症状Docsify 服务启动了但页面内容空白。解决方案# Ensure youre in the repository root cd Data-Science-For-Beginners # Check for index.html ls index.html # Serve with specific port docsify serve --port 3000 # Check browser console for errors (F12)必须确保在仓库根目录存在 index.html 的位置启动服务Docsify 才能正确解析_sidebar.md与各章节 Markdown端口冲突时可改用--port 3000等自定义端口。图片不显示症状图片显示为破损链接图标。解决方案检查图片路径是否为相对路径本项目各处文档普遍使用相对路径引用images/与translated_images/下的资源确认图片文件确实存在于仓库中清理浏览器缓存核对文件扩展名大小写部分系统区分大小写如images/与Images/会被视为不同路径。数据与文件问题课程数据集统一存放在仓库根目录 data 下包括birds.csv、mushrooms.csv、honey.csv、taxi.csv、diabetes.tsv、emails.csv、form.csv以及 data/COVID 子目录下的时间序列 CSV确诊、死亡、治愈全球数据。File Not Found 错误症状加载数据时抛FileNotFoundError。解决方案import os # Check current working directory print(os.getcwd()) # Use absolute path data_path os.path.join(os.getcwd(), data, filename.csv) df pd.read_csv(data_path) # Or use relative path from notebook location df pd.read_csv(../data/filename.csv) # Verify file exists print(os.path.exists(data/filename.csv))课程 Notebook 大多位于各章节的课程目录如3-Data-Visualization/09-visualization-quantities/相对仓库根目录的data/需写成../data/向上两级到根目录再进入data/。先用os.path.exists确认路径再决定使用绝对路径还是相对路径。CSV 读取错误症状读取 CSV 时出现编码、缺失值或分隔符问题。解决方案import pandas as pd # Try different encodings df pd.read_csv(file.csv, encodingutf-8) # or df pd.read_csv(file.csv, encodinglatin-1) # or df pd.read_csv(file.csv, encodingISO-8859-1) # Handle missing values df pd.read_csv(file.csv, na_values[NA, N/A, ]) # Specify delimiter if not comma df pd.read_csv(file.csv, delimiter;)UTF-8 读取失败时依次尝试latin-1、ISO-8859-1用na_values将业务空值标记统一为 NaN遇到制表符或分号分隔的文件如 data/diabetes.tsv需指定delimiter。大数据集内存不足症状加载大文件时抛MemoryError。解决方案# Read in chunks chunk_size 10000 chunks [] for chunk in pd.read_csv(large_file.csv, chunksizechunk_size): # Process chunk chunks.append(chunk) df pd.concat(chunks) # Or read specific columns only df pd.read_csv(file.csv, usecols[col1, col2]) # Use more efficient data types df pd.read_csv(file.csv, dtype{column_name: int32})三招依次升级分块读取chunksize避免一次性载入全部数据、只读所需列usecols减少内存占用、指定更紧凑的 dtype如int32替代默认int64。例如 data/COVID/time_series_covid19_confirmed_global.csv 这类按日期展开列宽表配合usecols可显著降低内存压力。性能问题Notebook 运行缓慢症状Notebook 执行耗时过长。解决方案重启内核并清理输出Kernel → Restart Clear Output关闭不再使用的 Notebook减少内存占用优化代码用向量化运算替代 Python 循环# Use vectorized operations instead of loops # Bad: result [] for x in data: result.append(x * 2) # Good: result data * 2 # NumPy/Pandas vectorization开发期先抽样大数据集# Work with sample during development df_sample df.sample(n1000) # or df.head(1000)课程涉及的数据集如 data/taxi.csv、COVID 时间序列在探索阶段先用抽样子集验证代码逻辑再切换到全量数据是提速的最直接手段。浏览器崩溃或无响应解决方案关闭不用的浏览器标签页清理浏览器缓存增大浏览器内存Chromechrome://settings/system改用 JupyterLab更省资源、界面更现代pip install jupyterlab jupyter lab如何获取更多帮助求助前自检清单通读本排障指南逐条比对在 GitHub Issues 中搜索是否已有相同问题复查 INSTALLATION.md安装指引与 USAGE.md课程使用工作流用搜索引擎检索完整错误信息。如何撰写高质量问题报告提交 Issue 或求助时务必包含以下五要素操作系统Windows、macOS 或 Linux注明发行版Python 版本运行python --version错误信息完整复制错误输出不要只贴一句话复现步骤报错前依次做了什么已尝试的方案例如重装包、重启 Jupyter 等。报告模板示例**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 Ive Tried:** - Ran pip install pandas - Restarted Jupyter相关文档索引文档用途INSTALLATION.md环境安装Git、Python、Jupyter、Node.js、Docsify 全流程USAGE.md课程使用方式、Notebook 工作流、Quiz 应用使用CONTRIBUTING.md参与贡献与提交 Issue 的规范README.md课程结构与章节总览for-teachers.md教师授课与作业批改指南附录快速诊断命令清单把下面这条命令序列作为环境自检工具按顺序执行即可快速定位绝大多数环境类故障# 1. 解释器与版本 python --version python3 --version # 2. 虚拟环境是否生效输出应指向 venv which python # 3. 核心数据科学包是否可用 python -c import pandas, numpy, matplotlib, seaborn, sklearn; print(OK) # 4. Jupyter 与内核 jupyter --version python -m ipykernel --version # 5. 前端工具链Quiz 应用与 Docsify 需要 node --version npm --version docsify --version # 6. Git 与仓库状态 git --version git status若某一步输出异常直接跳到上文对应小节按图索骥即可。这套诊断思路同样适用于 translations 下各语言版本希腊语译本见 translations/el/TROUBLESHOOTING.md因为各译本与原版结构完全一致。【免费下载链接】Data-Science-For-Beginners10 Weeks, 20 Lessons, Data Science for All!项目地址: https://gitcode.com/GitHub_Trending/da/Data-Science-For-Beginners创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考