在 Visual Studio 中為 Python 專案定義自訂指令

當你開發 Python 專案時，可能會切換到指令視窗來執行特定的腳本或模組、執行 pip 指令，或是用其他工具搭配程式碼。為了改善工作流程，你可以在 Visual Studio 的 Python 專案選單中新增自訂指令。自訂的 Python 指令可以在主控台視窗或 Visual Studio 輸出視窗執行。你也可以用正規表達式來指導 Visual Studio 如何解析指令輸出中的錯誤和警告。

先決條件

Windows 上的 Visual Studio 已安裝並支援 Python 工作負載。如需詳細資訊，請參閱在Visual Studio中安裝 Python 支援。

不支援 Visual Studio for Mac。 Visual Studio Code 在 Windows、Mac 和 Linux 上透過現有擴充功能與 Python 具有良好的相容性。

探索自訂指令

預設情況下， Python 專案選單包含兩個指令： 執行 PyLint（執行 PyLint ）和 執行 Mypy：

你自訂的任何 Python 指令都會出現在這個選單裡。自訂指令可以指 Python 檔案、Python 模組、內嵌 Python 程式碼、任意執行檔或 pip 指令。你也可以指定指令如何執行以及在哪裡執行。

你可以用多種方式新增自訂指令：

直接在 Python 專案檔（.pyproj）中定義自訂指令。這些指令適用於該特定專案。
在目標檔案（.targets）中定義自訂指令。你可以很容易地匯入這個檔案裡的指令，讓它們用於多個專案。
從 Visual Studio 裡定義自訂 Python 指令的專案範本建立一個 Python 專案。

Visual Studio 中的某些 Python 專案範本會透過使用 targets 檔案來新增自訂指令。 Bottle Web Project 和 Flask Web Project 範本新增了兩個指令， 分別是 Start server 和 Start debug server。 Django Web Project 範本新增了這些指令以及其他幾個指令：

重新載入專案以存取自訂指令

當專案在 Visual Studio 中開啟時，如果你在編輯器中對應的專案檔案做了修改，必須重新載入該專案才能套用這些變更。同樣地，在你定義 Python 專案檔案中的自訂 Python 指令後，你需要重新載入 Python 專案，指令才會出現在 Python 專案選單中。當你修改目標檔案中定義的自訂指令時，你需要為匯入該目標檔案的專案重建完整的 Visual Studio 解決方案。

一種常見的做法是直接在 Visual Studio 中對 Python 專案檔案進行修改：

在 Visual Studio 開啟你的 Python 專案。（當你在 Visual Studio 開啟專案時，該專案預設會 被載入 。）
在 解決方案總管中，右鍵點擊 Python 專案並選擇 「卸載專案」。

Visual Studio 會卸載專案，並在編輯器中開啟對應的 Python 專案檔案（.pyproj）。

如果專案檔案無法開啟，請再次右鍵點擊 Python 專案，選擇 編輯專案檔案：
在 Visual Studio 編輯器中對專案檔案做修改，然後儲存你的作品。
在 解決方案總管中，右鍵點擊已卸載的專案，選擇 「重新載入專案」。如果你嘗試在沒有將變更存檔到專案檔案的情況下重新載入專案，Visual Studio 會提示你完成該動作。

在開發自訂指令時，卸載、編輯、儲存、重新載入的過程可能會變得繁瑣。更有效率的工作流程是同時在 Visual Studio 載入專案，並在獨立編輯器中開啟 Python 專案檔案。您可以選用任意編輯器，例如另一個 Visual Studio 單獨實例、Visual Studio Code、記事本等等。當你在編輯器中儲存變更並切回 Visual Studio 後，Visual Studio 會偵測到該專案檔案的變更，並提示你採取行動：

選擇 Reload 或 Reload All，Visual Studio 會立即將你的專案檔案變更套用到開啟中的專案中。

用專案檔案新增自訂指令

以下步驟示範如何在 Python 專案檔案（.pyproj）中加入定義，並在 Visual Studio 重新載入專案，建立自訂指令。自訂指令會直接使用 python.exe 來執行專案啟動檔，這與在主工具列中使用「除錯>→開始不使用除錯工具」的效果基本相同。

在 Visual Studio 中，使用 Python Application 範本建立一個名為 Python-CustomOrders 的新 Python 專案。相關說明請參考快速入門：從範本建立 Python 專案。

Visual Studio 會建立 Python 專案，然後將其載入到你的使用者環境中。你可以透過專案檔案（.pyproj）來設定專案。這個檔案只有在專案開啟且 未載入時，才會在 Visual Studio 中顯示。專案中也有一個 Python 檔案（.py）用於應用程式程式碼。
在編輯器中開啟 Python_CustomCommands.py 應用程式檔案，並加入以下程式碼：
```
print("Hello custom commands")
```
在 解決方案總管中，右鍵點擊 Python 專案，選擇 Python，然後注意右鍵選單上的指令。目前，右鍵選單中唯一的指令是 Run PyLint 和 Run Mypy。當你定義自訂指令時，它們也會顯示在這個選單中。
在 Visual Studio 會話外啟動一個獨立的編輯器，並在編輯器中開啟 Python 專案檔案（Python-CustomCommands.pyproj）。（請務必打開專案檔案（.pyproj），而不是 Python 應用程式檔案（.py）。）
在專案檔案中，找到檔案末尾的結尾 </Project> 元素，並在結尾元素前緊接著新增以下 XML：
```
<PropertyGroup>
  <PythonCommands>
    $(PythonCommands);
  </PythonCommands>
</PropertyGroup>
```
儲存你的專案檔案變更，然後切回 Visual Studio。 Visual Studio 會偵測你的專案檔案變更並提示你採取行動。在提示時，選擇 重新載入 以更新你已開啟的專案檔案變更。
在 解決方案總管中，右鍵點擊 Python 專案，選擇 Python，然後在右鍵選單中勾選指令。

右鍵選單仍然只顯示 Run PyLint 和 Run Mypy 指令。你剛加入專案檔案的程式碼只是複製包含 <PythonCommands> 指令的預設屬性群組。下一步，你要為自訂指令加入更多程式碼。
切換到你正在更新專案檔案的編輯器。在元素<Target>中加入以下<Project>元素定義。你可以將定義置 <Target> 於先前描述的 <PropertyGroup> 定義之前或之後。

此<Target>元素定義了一個自訂指令，透過主控台視窗中的指令來執行專案的啟動檔案（由 python.exe 屬性識別）。屬性定義 ExecuteIn="consolepause" 會使用一個控制台，等待你選擇鍵來關閉控制台視窗。
```
<Target Name="Example_RunStartupFile" Label="Run startup file" Returns="@(Commands)">
  <CreatePythonCommandItem
    TargetType="script"
    Target="$(StartupFile)"
    Arguments=""
    WorkingDirectory="$(MSBuildProjectDirectory)"
    ExecuteIn="consolepause">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>
```
將<PythonCommands>屬性群組（在步驟 5中新增）替換為以下 XML。此語法定義元素 Name 的 <Target> 屬性，並將自訂指令加入 Python 的內容功能表中。這個指令的選單標籤是 「執行啟動檔案」。
```
  <PythonCommands>
    $(PythonCommands);
    Example_RunStartupFile
  </PythonCommands>
```
小提示

如果你希望你的自訂指令在由$(PythonCommands)詞元定義的預設指令之前出現在內容選單中，請將你的指令語法放在<Target>詞元之前。
儲存你的專案檔案變更，然後切回 Visual Studio。在提示時，重新載入你的專案。
在 解決方案總管中，右鍵點擊 Python 專案，選擇 Python，然後在右鍵選單中重新勾選指令。

現在自訂 的「執行啟動檔案 」指令就在選單裡了。如果你沒看到自訂指令，請確認你已經按照Name，將<Target>元素的屬性值加入<PythonCommands>元素中。同時也請參考本文後面故障排除部分列出的考量。
選擇 執行啟動檔案 指令。主控台視窗會打開，顯示 「Hello custom commands」文字， 接著「 按任意鍵繼續」。確認輸出並關閉控制台視窗。

備註

自訂指令腳本會在你 Python 專案啟用的環境中執行。
切換到帶有專案檔案的編輯器。在 <Target> 元素定義（步驟 8時加入）中，將屬性值改 ExecuteIn 為 output。
```
  <CreatePythonCommandItem
    ...
    ExecuteIn="output">
    ...
  </CreatePythonCommandItem>
```
儲存你的修改，切回 Visual Studio，然後重新載入你的專案。
再次從 Python 右鍵選單中選擇執行啟動檔案自訂指令。現在程式輸出顯示在 Visual Studio 的輸出 視窗，而非主控台視窗：
若要新增更多自訂指令，請依照相同流程操作：
1. 在專案檔案中為自訂指令定義合適的 <Target> 元素。
2. 將該Name元素的屬性值加入<Target><PythonCommands>屬性群組。
3. 將你的變更儲存到專案檔案。
4. 在 Visual Studio 重新載入你的專案。

使用專案屬性

在<Target>元素屬性值中參考專案屬性或環境變數時，請將屬性名稱放在$()標記內，例如$(StartupFile)和$(MSBuildProjectDirectory)。如需詳細資訊，請參閱 MSBuild 屬性。

如果你呼叫類似的指令 ($StartupFile) ，使用專案屬性（例如 StartupFile ）屬性，且因為標記未定義而失敗，Visual Studio 會停用該指令，直到你重新載入專案。如果你對專案做了修改屬性定義的變更，你的更改不會刷新相關指令的狀態。在這種情況下，你仍然需要重新載入專案。

了解 <目標> 元素結構

你可以用 <Target> 元素來定義自訂指令的細節。該 <Target> 元素的一般形式以以下偽碼形式表示：

<Target Name="Name1" Label="Display Name" Returns="@(Commands)">
    <CreatePythonCommandItem Target="filename, module name, or code"
        TargetType="executable/script/module/code/pip"
        Arguments="..."
        ExecuteIn="console/consolepause/output/repl[:Display name]/none"
        WorkingDirectory="..."
        ErrorRegex="..."
        WarningRegex="..."
        RequiredPackages="...;..."
        Environment="...">

      <!-- Output always appears in this form, with these exact attributes -->
      <Output TaskParameter="Command" ItemName="Commands" />
    </CreatePythonCommandItem>
  </Target>

目標屬性

下表列出了 <Target> 元素屬性。

Attribute	為必填項目	Description
`Name`	Yes	Visual Studio 專案中指令的識別碼。這個名稱必須加入 `<PythonCommands>` 屬性群組，命令才會顯示在 Python 的右鍵選單中。
`Label`	Yes	就是 Python 右鍵選單中出現的 UI 顯示名稱。
`Returns`	Yes	回傳的資訊必須包含 `@(Commands)` 標記，該標記用來識別目標為指令。

CreatePythonCommandItem 屬性

元素 <Target> 包含 <CreatePythonCommandItem> 和 <Output> 元素，定義自訂指令的詳細行為。下表列出可用的 <CreatePythonCommandItem> 元素屬性。所有屬性值皆不區分大小寫。

`Attribute`	為必填項目	Description
`TargetType`	Yes	指定`Target`屬性包含的內容以及如何將該值與`Arguments`屬性一起使用： - `executable`：執行在屬性 `Target` 中命名的可執行檔，並附加屬性 `Arguments` 中的值，就像直接在命令列輸入一樣。該值必須只包含程式名稱，且不得包含參數。 - `script`：執行 `python.exe` 指令，使用 `Target` 屬性中的檔名，接著是 `Arguments` 屬性中的值。 - `module`執行 `python -m` 命令，接著屬性中的 `Target` 模組名稱，再執行屬性中的 `Arguments` 值。 - `code`：執行屬性中包含的 `Target` 內嵌程式碼。忽略 `Arguments` 屬性值。 - `pip`：使用 `Target` 屬性中的命令執行 pip，然後是 `Arguments` 屬性中的值。如果屬性 `ExecuteIn` 設為 `output`，pip 會假設請求是執行 `install` 該指令，並以該 `Target` 屬性作為套件名稱。
`Target`	Yes	根據屬性值 `TargetType` 指定要使用的檔名、模組名稱、程式碼或 pip 指令。
`Arguments`	可選	提供一串參數（如有）可搭配 `Target` 屬性使用。 - 當 `TargetType` 屬性值為 `script`時， `Arguments` 該值會提供給 Python 程式，而非指令本身 `python.exe` 。 - 當 `TargetType` 屬性值為 `code`時， `Arguments` 該值被忽略。
`ExecuteIn`	Yes	指定執行指令的環境： - `console`：（預設）類似於直接在命令列輸入一樣，會執行具有 `Target` 值的 `Arguments` 屬性。當屬性 `Target` 執行時，會自動出現並關閉指令視窗。 - `consolepause`：行為與相同 `console`，但會等待按鍵點擊後才關閉視窗。 - `output`：執行該 `Target` 屬性，並在 Visual Studio 輸出視窗中顯示結果。如果屬性 `TargetType` 是 `pip`，Visual Studio 會將該 `Target` 屬性作為套件名稱，並附加 `Arguments` 屬性值。 - `repl`：在 `Target`中執行該屬性。可選的顯示名稱用於視窗標題。 - `none`：與行為相同 `console`。
`WorkingDirectory`	可選	用來識別執行該指令的資料夾。
`ErrorRegex` `WarningRegEx`	可選	僅在屬性 `ExecuteIn` 設定為 `output`時使用。這兩個屬性值都指定一個正規表達式，Visual Studio 用來解析指令輸出，並在錯誤清單視窗中顯示錯誤與警告。如果這些屬性未被指定，該指令不會影響錯誤清單視窗。想了解更多 Visual Studio 的期望，請參閱命名擷取群組。
`RequiredPackages`	可選	提供指令的套件需求清單，使用與 requirements.txt 檔案相同的格式（pip.readthedocs.io）。例如， Run PyLint 指令指定格式 `pylint>=1.0.0`。在執行指令之前，Visual Studio 會確認清單中的所有套件都已安裝。 Visual Studio 會用 pip 來安裝任何缺少的套件。
`Environment`	可選	在執行指令前，識別一串環境變數以供定義。每個變數都使用 `\<NAME>=\<VALUE>` 的形式，不同變數之間以分號分隔。具有多個值的變數必須包含在單引號或雙引號中，如 `'NAME=VALUE1;VALUE2'`。

正則表達式的具名捕捉群組

當 Visual Studio 解析自訂指令輸出的錯誤與警告時，預期和 ErrorRegex 屬性值中的WarningRegex正規表達式會使用以下命名群組：

(?<message>...)：錯誤內容。
(?<code>...)：錯誤代碼值。
(?<filename>...)：錯誤被回報的檔案名稱。
(?<line>...)：錯誤報告檔案中位置的行號。
(?<column>...)：錯誤報告所屬檔案位置的欄位編號。

例如，PyLint 會產生以下形式的警告：

************* Module hello
C:  1, 0: Missing module docstring (missing-docstring)

為了讓 Visual Studio 能從這些警告中擷取正確資訊並在錯誤清單視窗中顯示，WarningRegexRun Pylint 指令的屬性值如下：

^(?<filename>.+?)\((?<line>\d+),(?<column>\d+)\): warning (?<msg_id>.+?): (?<message>.+?)$]]

備註

msg_id屬性值的WarningRegex語法實際上應該是 code，如第 3680 期所述。

匯入帶有目標檔案的自訂指令

如果你在 Python 專案檔案中定義自訂指令，這些指令只會對該專案開放。當你想建立自訂指令並在多個專案中使用時，可以在目標檔案（<PythonCommands>）中定義<Target>包含所有元素的屬性群組，然後將該檔案匯入你的 Python 專案中。

目標檔案使用與 Python 專案檔案（.pyproj）相同的格式與語法來定義自訂指令。常見的配置元素包括 <PythonCommands>、 <Target>、 <CreatePythonCommandItem>、 <Output>及：

<Project xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
   <PropertyGroup>
     <PythonCommands>
       $(PythonCommands);
       <!-- Additional command names -->
     </PythonCommands>
   </PropertyGroup>

   <Target Name="..." Label="..." Returns="@(Commands)">
     <!-- CreatePythonCommandItem and Output elements... -->
   </Target>

   <!-- Any number of additional Target elements-->
</Project>

要將目標檔案匯入專案，請在專案檔案中該元素的<Import Project="(path)">任意位置新增<Project>一個元素。

舉例來說，如果你在 Python 專案的 targets 資料夾裡有一個名為 CustomCommands.targets 的專案檔案，請將以下程式碼加入專案檔案中：
```
<Import Project="targets/CustomCommands.targets"/>
```
如果你的專案檔案匯入了目標檔案，而你在專案在 Visual Studio 開啟時對目標檔案做了修改，你需要重建包含你專案的 Visual Studio 解決方案 ，而不只是專案本身。

範例命令

以下章節提供範例程式碼，供你為 Python 專案定義自訂指令。

執行 PyLint（模組目標）

以下程式碼出現在 Microsoft.PythonTools.targets 檔案中：

<PropertyGroup>
  <PythonCommands>$(PythonCommands);PythonRunPyLintCommand</PythonCommands>
  <PyLintWarningRegex>
    <![CDATA[^(?<filename>.+?)\((?<line>\d+),(?<column>\d+)\): warning (?<msg_id>.+?): (?<message>.+?)$]]>
  </PyLintWarningRegex>
</PropertyGroup>

<Target Name="PythonRunPyLintCommand"
        Label="resource:Microsoft.PythonTools.Common;Microsoft.PythonTools.Common.Strings;RunPyLintLabel"
        Returns="@(Commands)">
  <CreatePythonCommandItem Target="pylint.lint"
                           TargetType="module"
                           Arguments="&quot;--msg-template={abspath}({line},{column}): warning {msg_id}: {msg} [{C}:{symbol}]&quot; -r n @(Compile, ' ')"
                           WorkingDirectory="$(MSBuildProjectDirectory)"
                           ExecuteIn="output"
                           RequiredPackages="pylint&gt;=1.0.0"
                           WarningRegex="$(PyLintWarningRegex)">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>

用特定套件（pip target）執行 pip 安裝

以下指令會在 Visual Studio pip install my-package視窗執行該指令。你可以在開發套件並測試安裝時使用類似的指令。元素 <Target> 包含套件名稱而非 install 指令，這是在使用 ExecuteIn="output" 屬性定義時假設的。

<PropertyGroup>
  <PythonCommands>$(PythonCommands);InstallMyPackage</PythonCommands>
</PropertyGroup>

<Target Name="InstallMyPackage" Label="pip install my-package" Returns="@(Commands)">
  <CreatePythonCommandItem Target="my-package" TargetType="pip" Arguments=""
    WorkingDirectory="$(MSBuildProjectDirectory)" ExecuteIn="output">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>

顯示過時的 PIP 套件（PIP 目標）

以下指令執行 pip，透過 list 功能來識別過時的 pip 套件：

<PropertyGroup>
  <PythonCommands>$(PythonCommands);ShowOutdatedPackages</PythonCommands>
</PropertyGroup>

<Target Name="ShowOutdatedPackages" Label="Show outdated pip packages" Returns="@(Commands)">
  <CreatePythonCommandItem Target="list" TargetType="pip" Arguments="-o --format columns"
    WorkingDirectory="$(MSBuildProjectDirectory)" ExecuteIn="consolepause">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>

執行具備 consolepause 指令的執行檔

以下指令執行 where 函式，顯示從專案資料夾開始的 Python 檔案位置：

<PropertyGroup>
  <PythonCommands>$(PythonCommands);ShowAllPythonFilesInProject</PythonCommands>
</PropertyGroup>

<Target Name="ShowAllPythonFilesInProject" Label="Show Python files in project" Returns="@(Commands)">
  <CreatePythonCommandItem Target="where" TargetType="executable" Arguments="/r . *.py"
    WorkingDirectory="$(MSBuildProjectDirectory)" ExecuteIn="output">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>

執行伺服器並執行除錯伺服器指令

想了解網頁專案的 Start server 與 Start debug server 指令的定義，請參考 GitHub 上的 Microsoft.PythonTools.Web.targets 倉庫。

安裝用於開發的套件

以下程式碼執行 pip 以安裝套件：

<PropertyGroup>
  <PythonCommands>PipInstallDevCommand;$(PythonCommands);</PythonCommands>
</PropertyGroup>

<Target Name="PipInstallDevCommand" Label="Install package for development" Returns="@(Commands)">
    <CreatePythonCommandItem Target="pip" TargetType="module" Arguments="install --editable $(ProjectDir)"
        WorkingDirectory="$(WorkingDirectory)" ExecuteIn="Repl:Install package for development">
      <Output TaskParameter="Command" ItemName="Commands" />
    </CreatePythonCommandItem>
  </Target>

摘自 fxthomas/Example.pyproj.xml （GitHub），經授權使用。

產生 Windows 安裝程式

以下腳本會產生一個 Windows 安裝程式：

<PropertyGroup>
  <PythonCommands>$(PythonCommands);BdistWinInstCommand;</PythonCommands>
</PropertyGroup>

<Target Name="BdistWinInstCommand" Label="Generate Windows Installer" Returns="@(Commands)">
    <CreatePythonCommandItem Target="$(ProjectDir)setup.py" TargetType="script"
        Arguments="bdist_wininst --user-access-control=force --title &quot;$(InstallerTitle)&quot; --dist-dir=&quot;$(DistributionOutputDir)&quot;"
        WorkingDirectory="$(WorkingDirectory)" RequiredPackages="setuptools"
        ExecuteIn="Repl:Generate Windows Installer">
      <Output TaskParameter="Command" ItemName="Commands" />
    </CreatePythonCommandItem>
  </Target>

摘自 fxthomas/Example.pyproj.xml （GitHub），經授權使用。

生成 Python wheel 套件

以下腳本會產生一個 Python 輪子套件：

<PropertyGroup>
  <PythonCommands>$(PythonCommands);BdistWheelCommand;</PythonCommands>
</PropertyGroup>

<Target Name="BdistWheelCommand" Label="Generate Wheel Package" Returns="@(Commands)">

  <CreatePythonCommandItem Target="$(ProjectDir)setup.py" TargetType="script"
      Arguments="bdist_wheel --dist-dir=&quot;$(DistributionOutputDir)&quot;"
      WorkingDirectory="$(WorkingDirectory)" RequiredPackages="wheel;setuptools"
      ExecuteIn="Repl:Generate Wheel Package">
    <Output TaskParameter="Command" ItemName="Commands" />
  </CreatePythonCommandItem>
</Target>

摘自 fxthomas/Example.pyproj.xml （GitHub），經授權使用。

排除自訂指令問題

請參考以下章節，了解使用自訂指令時可能遇到的問題。

專案檔案未載入

此錯誤訊息表示專案檔案有語法錯誤。訊息中包含具體錯誤，並附有行號和字元位置。

指令執行後主控台視窗關閉

如果指令執行後主控台視窗立即關閉，請使用 ExecuteIn="consolepause" attribute 定義而非 ExecuteIn="console"。

如果你在 Python 右鍵選單中看不到自訂指令，請檢查以下項目：

確認該指令是否包含在 <PythonCommands> 屬性群組中。
確認指令清單中定義的指令名稱是否與元素中 <Target> 指定的名稱相符。

以下是範例。在以下的 XML 片段中，Example屬性群組中的<PythonCommands>名稱與元素定義中的ExampleCommand名稱不符<Target>。 Visual Studio 找不到名為 Example的指令，因此沒有任何指令出現。要麼在指令清單中使用 ExampleCommand ，要麼將目標名稱改為僅 Example為。

  <PropertyGroup>
    <PythonCommands>$(PythonCommands);Example</PythonCommands>
  </PropertyGroup>
  <Target Name="ExampleCommand" Label="Example Command" Returns="@(Commands)">
    <!-- ... -->
  </Target>

執行指令時出錯，未能取得指令目標

此錯誤訊息表示 <Target> 或 <CreatePythonCommandItem> 元素的內容不正確。

以下是造成此錯誤的一些可能原因：

所需 <Target> 元素屬性為空。
所需 TargetType 屬性為空或包含未識別的值。
所需 ExecuteIn 屬性為空或包含未識別的值。
ErrorRegex WarningRegex或屬性是在不設定ExecuteIn="output"屬性定義的情況下指定的。
元素中存在未識別的屬性。例如，屬性參考可能會被誤拼為 ArgumnetsArguments。

如果你參考的是未定義的屬性，屬性值可能是空的。如果你使用了 token $(StartupFile) ，但專案中沒有定義啟動檔，token 會解析成一個空字串。在這種情況下，你可能想定義一個預設值。例如，Bottle、Flask 和 Django 專案範本中定義的 Run server 和 Run debug server 指令預設使用 manage.py 檔案（如果專案屬性中未指定伺服器啟動檔）。

Visual Studio 停止回應，當機

如果你執行自訂指令時 Visual Studio 停止回應並當機，那你很可能是在嘗試執行帶有 ExecuteIn="output" 屬性定義的主控台指令。在這種情況下，Visual Studio 在解析輸出時可能會當機。為了避免此狀況，請改用 ExecuteIn="console" 屬性定義。更多資訊請參見第3681期。

指令未被識別為可操作的程式或批次檔案

當你設定 TargetType="executable" 屬性定義時，屬性中的 Target 值必須只有程式名稱，不能使用任何參數，例如 python 或 python.exe only。此時，將所有參數移至 Arguments 屬性。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-12

共用方式為

在 Visual Studio 中為 Python 專案定義自訂指令

先決條件

探索自訂指令

重新載入專案以存取自訂指令

用專案檔案新增自訂指令

使用專案屬性

了解 <目標> 元素結構

目標屬性

CreatePythonCommandItem 屬性

正則表達式的具名捕捉群組

匯入帶有目標檔案的自訂指令

範例命令

執行 PyLint（模組目標）

用特定套件（pip target）執行 pip 安裝

顯示過時的 PIP 套件（PIP 目標）

執行具備 consolepause 指令的執行檔

執行伺服器並執行除錯伺服器指令

安裝用於開發的套件

產生 Windows 安裝程式

生成 Python wheel 套件

排除自訂指令問題

專案檔案未載入

指令執行後主控台視窗關閉

選單中缺少指令

執行指令時出錯，未能取得指令目標

Visual Studio 停止回應，當機

指令未被識別為可操作的程式或批次檔案

意見反應

其他資源