疑難排解指南

本指南提供了解決在使用《初學者的數據科學》課程時可能遇到的常見問題的方法。

Python 和 Jupyter 問題

找不到 Python 或版本錯誤

問題： python: command not found 或 Python 版本錯誤

解決方法：

# Check Python version
python --version
python3 --version

# If Python 3 is installed as 'python3', create an alias
# On macOS/Linux, add to ~/.bashrc or ~/.zshrc:
alias python=python3
alias pip=pip3

# Or use python3 explicitly
python3 -m pip install jupyter

Windows 解決方法：

從 python.org 重新安裝 Python
安裝過程中勾選 "Add Python to PATH"
重新啟動終端機/命令提示符

虛擬環境啟動問題

問題： 虛擬環境無法啟動

解決方法：

Windows：

# If you get execution policy error
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

# Then activate
venv\Scripts\activate

macOS/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 venv

Jupyter 核心問題

問題： "Kernel not found" 或 "Kernel keeps dying"

解決方法：

# Reinstall kernel
python -m ipykernel install --user --name=datascience --display-name="Python (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 --name=venv --display-name="Python (venv)"

# In Jupyter, select Kernel -> Change kernel -> Python (venv)

套件和依賴問題

匯入錯誤

問題： ModuleNotFoundError: No module named 'pandas'（或其他套件）

解決方法：

# 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__)"

Pip 安裝失敗

問題： pip install 因權限錯誤而失敗

解決方法：

# 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

套件版本衝突

問題： 套件版本不兼容

解決方法：

# 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 pandas==1.3.0
pip install numpy==1.21.0

# Or let pip resolve dependencies
pip install jupyter pandas numpy matplotlib seaborn scikit-learn

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:$PATH"

Notebook 無法載入或儲存

問題： "Notebook failed to load" 或儲存錯誤

解決方法：

檢查檔案權限

# Make sure you have write permissions
ls -l notebook.ipynb
chmod 644 notebook.ipynb  # If needed

檢查檔案是否損壞

# 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
重新啟動核心：核心選單 → Restart
檢查程式碼中的無限迴圈
清除輸出：Cell → All Output → Clear

圖表無法顯示

問題： matplotlib 圖表未在 Notebook 中顯示

解決方法：

# 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

測驗應用程式問題

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

測驗應用程式無法啟動

問題： 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

埠已被佔用

問題： "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 8081

測驗無法載入或顯示空白頁面

問題： 測驗應用程式載入但顯示空白頁面

解決方法：

檢查瀏覽器主控台中的錯誤（按 F12）
清除瀏覽器快取和 Cookie
嘗試使用其他瀏覽器
確保 JavaScript 已啟用
檢查是否有廣告攔截器干擾

# Rebuild the app
npm run build
npm run serve

Git 和 GitHub 問題

Git 未被識別

問題： git: command not found

解決方法：

Windows：

從 git-scm.com 安裝 Git
安裝後重新啟動終端機

macOS：

注意： 如果尚未安裝 Homebrew，請先按照 https://brew.sh/ 的指示進行安裝。

# Install via Homebrew
brew install git

# Or install Xcode Command Line Tools
xcode-select --install

Linux：

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

Clone 失敗

問題： 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

權限被拒絕（publickey）

問題： SSH 金鑰身份驗證失敗

解決方法：

# Generate SSH key
ssh-keygen -t ed25519 -C "your_email@example.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

Docsify 文件問題

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 you're 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)

圖片無法顯示

問題： 圖片顯示為損壞的連結圖示

解決方法：

檢查圖片路徑是否為相對路徑
確保圖片檔案存在於存儲庫中
清除瀏覽器快取
驗證檔案副檔名是否匹配（某些系統對大小寫敏感）

數據和檔案問題

找不到檔案錯誤

問題： 載入數據時出現 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'))

CSV 讀取錯誤

問題： 讀取 CSV 檔案時出現錯誤

解決方法：

import pandas as pd

# Try different encodings
df = pd.read_csv('file.csv', encoding='utf-8')
# or
df = pd.read_csv('file.csv', encoding='latin-1')
# or
df = pd.read_csv('file.csv', encoding='ISO-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=';')

大型數據集的記憶體錯誤

問題： 載入大型檔案時出現 MemoryError

解決方法：

# Read in chunks
chunk_size = 10000
chunks = []
for chunk in pd.read_csv('large_file.csv', chunksize=chunk_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'})

效能問題

Notebook 效能緩慢

問題： Notebook 執行速度非常慢

解決方法：

重新啟動核心並清除輸出
- 核心 → Restart & Clear Output
關閉未使用的 Notebook
優化程式碼：

# 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(n=1000)  # or df.head(1000)

瀏覽器崩潰

問題： 瀏覽器崩潰或無法響應

解決方法：

關閉未使用的標籤頁
清除瀏覽器快取
增加瀏覽器記憶體（Chrome：chrome://settings/system）
使用 JupyterLab 替代：

pip install jupyterlab
jupyter lab

獲取額外幫助

在尋求幫助之前

檢查本疑難排解指南
搜索 GitHub Issues
查看 INSTALLATION.md 和 USAGE.md
嘗試在線搜索錯誤訊息

如何尋求幫助

在創建問題或尋求幫助時，請提供以下信息：

操作系統：Windows、macOS 或 Linux（哪個版本）
Python 版本：執行 python --version
錯誤訊息：複製完整的錯誤訊息
重現步驟：錯誤發生前的操作
已嘗試的解決方法：您已嘗試的解決方案

範例：

**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

社群資源

GitHub Issues：創建問題
Discord：加入我們的社群
討論區：GitHub Discussions
Microsoft Learn：問答論壇

FilesExpand file tree

TROUBLESHOOTING.md

Latest commit

History

TROUBLESHOOTING.md

File metadata and controls

疑難排解指南

目錄

Python 和 Jupyter 問題

找不到 Python 或版本錯誤

虛擬環境啟動問題

Jupyter 核心問題

套件和依賴問題

匯入錯誤

Pip 安裝失敗

套件版本衝突

Jupyter Notebook 問題

Jupyter 無法啟動

Notebook 無法載入或儲存

程式碼單元無法執行

圖表無法顯示

測驗應用程式問題

npm install 失敗

測驗應用程式無法啟動

埠已被佔用

測驗無法載入或顯示空白頁面

Git 和 GitHub 問題

Git 未被識別

Clone 失敗

權限被拒絕（publickey）

Docsify 文件問題

Docsify 命令未找到

文件無法載入

圖片無法顯示

數據和檔案問題

找不到檔案錯誤

CSV 讀取錯誤

大型數據集的記憶體錯誤

效能問題

Notebook 效能緩慢

瀏覽器崩潰

獲取額外幫助

在尋求幫助之前

如何尋求幫助

社群資源

相關文件