VS Code 中的 Jupyter Notebook

Jupyter（前身為 IPython Notebook）是一個開源專案，可讓您輕鬆地將 Markdown 文字與可執行的 Python 原始程式碼結合在一個稱為筆記本 (notebook) 的畫布上。Visual Studio Code 原生支援 Jupyter Notebook（透過 Jupyter 擴充功能），也支援透過 Python 程式碼檔案來使用。本主題涵蓋 Jupyter Notebook 的原生支援，並示範如何進行下列操作：

• 建立、開啟與儲存 Jupyter Notebook
• 使用 Jupyter 程式碼儲存格
• 使用變數總管與資料檢視器來檢視、檢查與篩選變數
• 連線至遠端 Jupyter 伺服器
• 偵錯 Jupyter Notebook

設定您的環境

若要在 Jupyter Notebook 中使用 Python，您必須在 VS Code 中啟用 Anaconda 環境，或是安裝了 Jupyter 套件的其他 Python 環境。若要選取環境，請使用命令選擇區（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中的 Python: Select Interpreter 命令。

一旦啟用了適當的環境，您就可以建立並開啟 Jupyter Notebook、連線至遠端 Jupyter 伺服器以執行程式碼儲存格，並將 Jupyter Notebook 匯出為 Python 檔案。

環境變數

環境變數會從 .env 檔案載入。請參閱 Python 環境說明文件中的該章節。

工作區信任

開始使用 Jupyter Notebook 時，請務必確認您是在受信任的工作區中作業。有害的程式碼可能會被嵌入筆記本中，而工作區信任 (Workspace Trust) 功能可讓您指定哪些資料夾及其內容應允許或限制自動執行程式碼。

如果您嘗試在執行限制模式 (Restricted Mode) 的不受信任工作區中開啟筆記本，您將無法執行儲存格，且豐富的輸出內容將會被隱藏。

建立或開啟 Jupyter Notebook

您可以透過執行命令選擇區（⇧⌘P (Windows, Linux Ctrl+Shift+P)）中的 Create: New Jupyter Notebook 命令，或是在工作區中建立新的 .ipynb 檔案來建立 Jupyter Notebook。

接著，使用右上角的核心選擇器 (kernel picker) 選擇一個核心。

選擇核心後，位於每個程式碼儲存格右下角的語言選擇器會自動更新為該核心所支援的語言。

如果您已有 Jupyter Notebook，可以透過對該檔案按一下右鍵並選擇以 VS Code 開啟，或是透過 VS Code 檔案總管將其開啟。

執行儲存格

執行單一程式碼儲存格

加入程式碼後，您可以使用程式碼儲存格左側的執行 (Run) 圖示來執行儲存格，執行結果將會顯示在程式碼儲存格下方。

若要執行選定的程式碼儲存格，您也可以在命令模式與編輯模式下使用鍵盤快速鍵。Ctrl+Enter 可執行目前選定的儲存格。Shift+Enter 可執行目前選定的儲存格並在下方立即插入一個新儲存格（焦點移至新儲存格）。Alt+Enter 可執行目前選定的儲存格並在下方立即插入一個新儲存格（焦點保留在目前儲存格）。

執行多個程式碼儲存格

執行多個程式碼儲存格的方法有多種。您可以使用 Notebook 編輯器主工具列中的雙箭頭來執行筆記本中的所有儲存格，或是透過在目前程式碼儲存格上方或下方選擇全部執行 (Run All)、執行上方全部 (Run All Above) 或 執行下方全部 (Run All Below)。

執行區段中的儲存格

為了更輕鬆地執行筆記本中相關聯的儲存格，您可以使用執行區段中的儲存格 (Run Cells in Section) 動作來執行由 Markdown 區段標題分組的儲存格。此動作可在筆記本的大綱檢視與黏貼式捲動 (Sticky Scroll) 元素中使用。

在黏貼式捲動元素中，以右鍵按一下您選擇的標題，並透過內容選單中的動作執行該區段。在大綱檢視中，選取懸停或選取時出現的工具列圖示，然後透過呈現的動作執行單一儲存格或一組儲存格。

儲存您的 Jupyter Notebook

您可以使用鍵盤快速鍵 Ctrl+S 或透過 檔案 (File) > 儲存 (Save) 來儲存 Jupyter Notebook。

匯出您的 Jupyter Notebook

您可以將 Jupyter Notebook 匯出為 Python 檔案 (.py)、PDF 或 HTML 檔案。若要匯出，請在主工具列上選擇 ... > 匯出 (Export)。接著會出現一個下拉式選單，列出檔案格式選項。

注意：若要匯出為 PDF，您必須安裝 TeX。如果您尚未安裝，選擇 PDF 選項時會收到需要安裝的通知。此外請注意，如果您的筆記本中有僅限 SVG 的輸出內容，這些內容將不會顯示在 PDF 中。若要在 PDF 中顯示 SVG 圖形，請確保您的輸出包含非 SVG 的影像格式，或是先匯出為 HTML，再使用瀏覽器另存為 PDF。

在 Notebook 編輯器中使用程式碼儲存格

Notebook 編輯器讓您能輕鬆地在 Jupyter Notebook 中建立、編輯與執行程式碼儲存格。

建立程式碼儲存格

預設情況下，空白筆記本會提供一個空的程式碼儲存格供您開始使用，而既有的筆記本則會在底部放置一個。將您的程式碼加入空的程式碼儲存格即可開始。

msg = "Hello world"
print(msg)

程式碼儲存格模式

使用程式碼儲存格時，儲存格可能有三種狀態：未選取、命令模式與編輯模式。程式碼儲存格與編輯器邊框左側的垂直條顯示了儲存格目前的狀態。當沒有垂直條時，表示未選取該儲存格。當儲存格被選取時，它可能處於命令模式或編輯模式。

在命令模式下，實心垂直條會出現在儲存格左側。此時可對儲存格進行操作並接受鍵盤指令。

在編輯模式下，實心垂直條旁會出現儲存格編輯器的邊框。此時可修改儲存格的內容（程式碼或 Markdown）。

若要切換模式，您可以使用鍵盤或滑鼠。在鍵盤上，按 Enter 鍵可切換至編輯模式，按 Esc 鍵可切換至命令模式。使用滑鼠時，按一下儲存格左側的垂直條，或點擊程式碼儲存格中程式碼/Markdown 區域以外的地方即可。

加入額外的程式碼儲存格

您可以使用主工具列、儲存格的「加入儲存格」工具列（懸停時顯示），以及鍵盤指令來加入程式碼儲存格。

若要在目前選取的儲存格下方加入新儲存格，請使用主工具列中的加號圖示或儲存格的懸停工具列。

當程式碼儲存格處於命令模式時，使用 A 鍵可在選取儲存格上方加入儲存格，使用 B 鍵可在下方加入儲存格。

選取程式碼儲存格

您可以使用滑鼠或鍵盤上的上下箭頭鍵來變更選取的程式碼儲存格。當程式碼儲存格處於命令模式時，您也可以使用 J 鍵（向下）與 K 鍵（向上）。

選取多個程式碼儲存格

若要選取多個儲存格，請先將一個儲存格設為選取模式。填滿的背景表示該儲存格已被選取。若要選取連續儲存格，請按住 Shift 鍵並點擊您要選取的最後一個儲存格。若要選取任意組儲存格，請按住 Ctrl 鍵並點擊您想要加入選取範圍的儲存格。

移動程式碼儲存格

您可以透過拖放方式在筆記本中上下移動儲存格。對於程式碼儲存格，拖放區域位於儲存格編輯器的左側，如下所示。對於已呈現的 Markdown 儲存格，您可以點擊任何地方進行拖放。

若要移動多個儲存格，您可以使用選取範圍中任何儲存格的相同拖放區域。

鍵盤快速鍵 Alt+箭頭鍵 也可以移動一個或多個選定的儲存格。

刪除程式碼儲存格

若要刪除程式碼，您可以使用程式碼儲存格工具列中的刪除 (Delete) 圖示。當選取的程式碼儲存格處於命令模式時，您可以使用鍵盤快速鍵 dd。

復原最後一次變更

您可以使用 z 鍵來復原先前的變更。例如，如果您不小心進行了編輯，可以復原至先前的正確狀態；或者如果不小心刪除了儲存格，也可以將其恢復。

切換程式碼與 Markdown

Notebook 編輯器讓您能輕鬆地在 Markdown 與程式碼之間變更儲存格類型。選取儲存格右下角的語言選擇器，即可在 Markdown 以及所選核心支援的任何其他語言之間切換。

您也可以使用鍵盤來變更儲存格類型。當儲存格被選取且處於命令模式時，M 鍵可將儲存格類型變更為 Markdown，Y 鍵可將其變更為程式碼。

一旦設定為 Markdown，您就可以在程式碼儲存格中輸入 Markdown 格式的內容。

若要呈現 Markdown 儲存格，您可以選取儲存格工具列中的勾選圖示，或使用鍵盤快速鍵 Ctrl+Enter 與 Shift+Enter。

清除輸出或重新啟動/中斷核心

如果您想要清除所有程式碼儲存格的輸出，或重新啟動/中斷核心，可以使用主 Notebook 編輯器工具列來完成。

啟用/停用行號

在命令模式下，您可以使用 L 鍵來啟用或停用單一程式碼儲存格內的行號。

若要切換整個筆記本的行號顯示，請在任一儲存格的命令模式下使用 Shift+L。

目錄

若要導覽您的筆記本，請開啟活動列 (Activity Bar) 中的「檔案總管」，然後開啟側邊欄 (Side Bar) 中的大綱 (Outline) 索引標籤。

您可以使用大綱檢視中的篩選控制項來包含 Markdown 標題、程式碼儲存格與程式碼儲存格符號。這些篩選器對應至下列設定：

• notebook.outline.showMarkdownHeadersOnly
• notebook.outline.showCodeCells
• notebook.outline.showCodeCellSymbols

注意：預設情況下，大綱只會顯示 Markdown。若要顯示程式碼儲存格，請啟用下列設定：Notebook > Outline: Show Code Cells。

Jupyter Notebook 編輯器中的 IntelliSense 支援

Python Jupyter Notebook 編輯器視窗具有完整的 IntelliSense 功能——包括程式碼完成、成員列表、方法的快速資訊與參數提示。您在 Notebook 編輯器視窗中輸入時，將能與在程式碼編輯器中一樣高效。

變數總管與資料檢視器

在 Python Notebook 中，您可以檢視、檢查、排序與篩選目前 Jupyter 工作階段中的變數。在執行程式碼與儲存格後，選取主工具列中的變數 (Variables) 圖示，即可看到目前變數的列表，該列表會隨著程式碼中變數的使用而自動更新。變數窗格將會顯示在筆記本底部。

資料檢視器

若要取得有關變數的更多資訊，您也可以按兩下資料列，或使用變數旁的在資料檢視器中顯示變數 (Show variable in data viewer) 按鈕，以在資料檢視器中更詳細地查看該變數。

或者，您也可以使用其他擴充功能（如 Data Wrangler）提供的資料檢視功能。Data Wrangler 擴充功能提供豐富的使用者介面，可顯示資料的洞察資訊，並協助您執行資料分析 (profiling)、品質檢查、轉換等操作。請參閱我們的說明文件以深入了解 Data Wrangler 擴充功能。

篩選資料列

您可以透過在每個欄位頂端的文字方塊中輸入內容來篩選資料檢視器中的資料列。輸入您要搜尋的字串，包含該字串的任何資料列都會被找到。

如果您想搜尋完全相符的項目，請在篩選條件前加上 '='。

若要進行更複雜的篩選，可以輸入正規表示式 (regular expression)。

儲存圖表

若要儲存筆記本中的圖表，只需將滑鼠懸停在輸出內容上，然後選取右上角的儲存 (Save) 圖示即可。

注意：支援呈現使用 matplotlib 與 Altair 建立的圖表。

自訂 Notebook 比對 (diffing)

在底層，Jupyter Notebook 是 JSON 檔案。JSON 檔案中的片段被呈現為儲存格，這些儲存格由三個元件組成：輸入、輸出與中繼資料。使用行比對 (line-based diffing) 來比較筆記本中的變更非常困難且難以解析。Notebook 的豐富比對編輯器讓您能輕鬆查看儲存格中每個元件的變更。

您甚至可以自訂要在比對檢視中顯示哪些類型的變更。在右上角，選取工具列中的溢出選單項目，以自訂要包含的儲存格元件。輸入差異將會始終顯示。

若要深入了解 VS Code 中的 Git 整合，請參閱 VS Code 中的原始程式碼控制 (Source Control)。

偵錯 Jupyter Notebook

偵錯 Jupyter Notebook 有兩種不同方式：一種稱為「逐行執行 (Run by Line)」的簡易模式，以及完整的偵錯模式。

注意：這兩項功能都需要 ipykernel 6+。有關安裝或升級 ipykernel 的詳細資訊，請參閱此維基頁面。

逐行執行 (Run by Line)

「逐行執行」讓您可以一次執行儲存格中的一行程式碼，而不會受到其他 VS Code 偵錯功能的干擾。若要開始，請選取儲存格工具列中的逐行執行 (Run by Line) 按鈕。

使用同一個按鈕可逐條語句推進。您可以選取儲存格的停止 (Stop) 按鈕提前結束，或選取工具列中的繼續 (Continue) 按鈕以執行至儲存格末尾。

偵錯儲存格 (Debug Cell)

如果您想要使用 VS Code 支援的完整偵錯功能，例如中斷點以及進入其他儲存格和模組的能力，可以使用完整的 VS Code 偵錯工具。

1. 首先，透過按一下筆記本儲存格的左邊界來設定您需要的中斷點。
2. 接著，選取執行 (Run) 按鈕旁邊選單中的偵錯儲存格 (Debug Cell) 按鈕。這將會在偵錯工作階段中執行該儲存格，並在執行到的任何程式碼處（即使該程式碼位於不同的儲存格或 .py 檔案中）暫停於您的中斷點。
3. 您可以像在 VS Code 中一樣正常使用偵錯檢視、偵錯主控台以及偵錯工具列上的所有按鈕。

請注意，在 Jupyter Notebook 中偵錯儲存格時，不會使用 launch.json 中的任何偵錯設定。您可以改為透過 jupyter.debugJustMyCode 等設定進行自訂。

搜尋筆記本

您可以使用鍵盤快速鍵 Ctrl/Cmd + F 來搜尋整個筆記本（或透過篩選搜尋選項來搜尋部分內容）。按一下篩選選項（漏斗圖示）以搜尋：

• Markdown 儲存格輸入 (Markdown Source)
• Markdown 儲存格輸出 (Rendered Markdown)
• 程式碼儲存格輸入 (Code Cell Source)
• 程式碼儲存格輸出 (Cell Output)

預設情況下，筆記本搜尋僅篩選儲存格輸入。

連線至遠端 Jupyter 伺服器

您可以透過連線至遠端 Jupyter 伺服器，將 Jupyter Notebook 中的密集運算工作分流至其他電腦。連線後，程式碼儲存格將在遠端伺服器上執行，而非在本機電腦上。

若要連線至遠端 Jupyter 伺服器：

1. 開啟筆記本右上方的「核心選擇器」按鈕（或從命令選擇區執行 Notebook: Select Notebook Kernel 命令）。

   

2. 選取 Existing Jupyter Server 選項以連線至現有的 Jupyter 伺服器。

   

3. 首次連線至現有伺服器時，選取 Enter the URL of the running Jupyter server。

   

4. 當提示 Enter the URL of the running Jupyter server 時，請提供伺服器的 URI (主機名稱)，並包含 ?token= URL 參數中的驗證權杖。（如果您是在啟用驗證權杖的情況下在 VS Code 終端機中啟動伺服器，包含權杖的 URL 通常會出現在終端機輸出中，您可以從該處複製。）或者，您可以在提供 URI 後指定使用者名稱與密碼。

   

注意：為了增加安全性，Microsoft 建議您設定 Jupyter 伺服器並採取安全預防措施，例如 SSL 與權杖支援。這有助於確保發送至 Jupyter 伺服器的請求皆經過驗證，且與遠端伺服器的連線均已加密。有關保護筆記本伺服器的指引，請參閱 Jupyter 說明文件。

資料科學設定檔範本

設定檔 (Profiles) 讓您能根據目前的專案或任務，快速切換擴充功能、設定與 UI 配置。為了協助您開始使用 Jupyter Notebook，您可以使用資料科學設定檔範本，這是一個精選的設定檔，包含了有用的擴充功能、設定與程式碼片段。您可以直接使用此設定檔範本，或以此為基礎進一步自訂，以符合您自己的工作流程。

您可以透過「設定檔」(Profiles) > 「建立設定檔...」(Create Profile...) 下拉式選單來選擇設定檔範本

選擇設定檔範本後，您可以審閱相關的設定和擴充功能，並移除您不想包含在新的設定檔中的項目。在根據範本建立新設定檔後，您對設定、擴充功能或 UI 所做的任何變更，都會儲存在您的設定檔中。