dotnet publish

本文適用於： ✔️ .NET 6 SDK 及後續版本

名字

dotnet publish - 將應用程式及其相依性發佈至部署至主控系統的資料夾。

概要

dotnet publish [<PROJECT>|<SOLUTION>|<FILE>] [-a|--arch <ARCHITECTURE>]
    [--artifacts-path <ARTIFACTS_DIR>]
    [-c|--configuration <CONFIGURATION>] [--disable-build-servers]
    [-f|--framework <FRAMEWORK>] [--force] [--interactive]
    [--manifest <PATH_TO_MANIFEST_FILE>] [--no-build] [--no-dependencies]
    [--no-restore] [--nologo] [-o|--output <OUTPUT_DIRECTORY>]
    [--os <OS>] [-p|--property:<PROPERTYNAME>=<VALUE>]
    [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--sc|--self-contained] [--no-self-contained]
    [-s|--source <SOURCE>] [--tl:[auto|on|off]]
    [--ucr|--use-current-runtime]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet publish -h|--help

描述

dotnet publish 編譯應用程式、讀取其在項目檔中指定的相依性，並將產生的檔案集發佈至目錄。 輸出包含下列資產：

• 元件中具有 dll 延伸模組的中繼語言 （IL） 程序代碼。
• 包含專案所有相依性的 .deps.json 檔案。
• .runtimeconfig.json 檔案，指定應用程式預期的共用運行時間，以及運行時間的其他組態選項（例如垃圾收集類型）。
• 從 NuGet 快取複製到輸出資料夾的應用程式相依性。

dotnet publish 命令的輸出已準備好部署至主控系統（例如伺服器、PC、Mac、膝上型電腦）來執行。 這是準備應用程式以進行部署的唯一正式支援方式。 根據專案指定的部署類型，主機系統可能安裝或未安裝 .NET 共享執行時。 欲了解更多資訊，請參閱 .NET 應用程式發佈概覽。

隱含還原

您不需要執行 dotnet restore，因為它是由需要還原的所有命令隱含執行，例如 dotnet new、dotnet build、dotnet run、dotnet test、dotnet publish和 dotnet pack。 若要停用隱含還原，請使用 --no-restore 選項。

指令在某些明確還原有意義的情境下仍然有用，例如Azure DevOps服務<>中的 持續整合建置，或是需要明確控制還原時間的建置系統。

如需如何管理 NuGet 摘要的資訊，請參閱 dotnet restore 檔案。

MSBuild

dotnet publish 命令會呼叫 MSBuild，以叫用 Publish 目標。 如果 IsPublishable 屬性 設定為特定專案的 false，則無法叫用 Publish 目標，而且 dotnet publish 命令只會在專案上執行隱含的 dotnet restore。

傳遞至 dotnet publish 的任何參數會傳遞至 MSBuild。 -c 和 -o 參數分別對應至 MSBuild 的 Configuration 和 PublishDir 屬性。

dotnet publish 命令接受 MSBuild 選項，例如設定屬性和 -p 來定義記錄器 -l。 例如，您可以使用 下列格式來設定 MSBuild 屬性：-p:<NAME>=<VALUE>。

.pubxml 檔案

您也可以參考 .pubxml 檔案來設定發行相關屬性。 例如：

dotnet publish -p:PublishProfile=FolderProfile

上述範例使用 FolderProfile.pubxml 檔案，該檔案位於 <project_folder>/Properties/PublishProfiles 資料夾中。 如果您在設定 PublishProfile 屬性時指定路徑和擴展名，則會忽略它們。 MSBuild 預設會在 Properties/PublishProfiles 資料夾中尋找，並假設 pubxml 擴展名。 若要指定路徑和檔名，包括擴展名，請設定 PublishProfileFullPath 屬性，而不是 PublishProfile 屬性。

在 .pubxml 檔案中：

• PublishUrl Visual Studio 用來表示發佈目標。
• CLI 會使用 PublishDir 來表示發佈目標。

如果您想要讓案例在所有位置運作，您可以將這兩個屬性初始化為 .pubxml 檔案中的相同值。 當GitHub問題解決後，dotnet/sdk#20931 解決後，只需設定其中一項屬性即可。

.pubxml 檔案中的某些屬性僅由 Visual Studio 尊重，對 dotnet publish 不影響。 我們正努力讓 CLI 更符合 Visual Studio 的行為。 但 CLI 永遠不會使用某些屬性。 CLI 和 Visual Studio 都負責發佈的打包部分，dotnet/sdk#29817 計畫新增更多相關屬性的支援。 但是 CLI 不會執行發布的部署自動化層面，也不會支援與發布相關的屬性。 不支援的最值得注意 dotnet publish 屬性是下列會影響組建的屬性：

• LastUsedBuildConfiguration
• Configuration
• Platform
• LastUsedPlatform
• TargetFramework
• TargetFrameworks
• RuntimeIdentifier
• RuntimeIdentifiers

MSBuild 屬性

下列 MSBuild 屬性會變更 dotnet publish的輸出。

• PublishReadyToRun

  將應用程式元件編譯為 ReadyToRun （R2R） 格式。 R2R 是預先編譯的一種形式。 如需詳細資訊，請參閱 ReadyToRun 映射。

  若要檢視可能導致執行時間失敗之遺漏相依性的警告，請使用 PublishReadyToRunShowWarnings=true。

  建議您在發行配置檔中指定 PublishReadyToRun，而不是在命令行上指定。

• PublishSingleFile

  將應用程式封裝成平臺特定的單一檔案可執行檔。 如需單一檔案發佈的詳細資訊，請參閱單一檔案套件組合器設計檔。 當這個屬性設定為 true時， PublishSelfContained 屬性會隱含地設定為 true。

  建議您在項目檔中指定此選項，而不是在命令行上指定此選項。

• PublishTrimmed

  修剪未使用的連結庫，以在發佈獨立可執行檔時減少應用程式的部署大小。 如需詳細資訊，請參閱 修剪獨立式部署和可執行檔案。 自 .NET 6 SDK 起即可取得。

  建議您在項目檔中指定此選項，而不是在命令行上指定此選項。

如需詳細資訊，請參閱下列資源：

• MSBuild 命令行參考
• Visual Studio 發佈 profiles （.pubxml） for the app deployment for ASP.NET Core app
• dotnet MSbuild

工作負載指令清單下載

當您執行此命令時，它會起始工作負載廣告指令清單的異步背景下載。 如果此命令完成時仍在執行下載，則會停止下載。 如需詳細資訊，請參閱廣告指令清單。

參數

PROJECT | SOLUTION | FILE

要操作的專案或解決方案或 C# （檔案型應用程式） 檔案。 如果未指定檔案，MSBuild 會在目前目錄中搜尋專案或解決方案。

• PROJECT 是 C#、F# 或 Visual Basic 專案檔案的路徑與檔名，或是包含 C#、F# 或 Visual Basic 專案檔案的目錄路徑。

• SOLUTION 是方案檔的路徑和檔名（.sln 或 .slnx 擴展名），或包含方案檔之目錄的路徑。

• FILE 是.NET 10中新增的參數。 檔案型應用程式的路徑和檔案名稱。 檔案型應用程式包含在建置和執行的單一檔案中，而沒有對應的專案 （.csproj） 檔案。 如需詳細資訊，請參閱 建置檔案型 C# 應用程式。

選項

• -a|--arch <ARCHITECTURE>

  指定目標架構。 這是設定 運行時間標識碼 （RID）的速記語法，其中提供的值會與預設 RID 結合。 例如，在 win-x64 電腦上，指定 --arch x86 將 RID 設定為 win-x86。 如果您使用此選項，請勿使用 [-r|--runtime] 選項。 自 .NET 6 預覽版 7 起可取得。

• --artifacts-path <ARTIFACTS_DIR>

  執行命令的所有建置輸出檔案都會位於指定路徑下的子資料夾中，並以專案分隔。 如需詳細資訊，請參閱 成品輸出配置。 此選項及所提供的值必須在任何依賴其他dotnet指令輸出的指令中明確串dotnet接，例如使用 dotnet build --no-restore 和 dotnet publish --no-build時。 自 .NET 8 SDK 起即可取得。

• -c|--configuration <CONFIGURATION>

  定義組建組態。 如果你使用 .NET 8 SDK 或更新版本開發，該指令預設使用 Release 設定，適用於 TargetFramework 設定為 net8.0 或更新版本的專案。 舊版 SDK 和舊版目標架構的預設組建組態 Debug。 您可以在項目設定中覆寫預設值，或使用此選項。 如需詳細資訊，請參閱 'dotnet publish' 使用發行組態，'dotnet pack' 使用發行組態。

• --disable-build-servers

  強制命令忽略任何持續性組建伺服器。 此選項提供一致的方式來停用所有建置快取的使用，以強制從頭開始建置。 當快取可能損毀或因某些原因而不正確時，不依賴快取的組建很有用。 自 .NET 7 SDK 起即可取得。

• -f|--framework <FRAMEWORK>

  發行指定 目標架構的應用程式。 您必須在項目檔中指定目標架構。

• --force

  強制解析所有相依性，即使上次還原成功也一樣。 指定此旗標與刪除 project.assets.json 檔案相同。

• --interactive

  允許命令停止並等候使用者輸入或動作。 例如，若要完成驗證。

• --manifest <PATH_TO_MANIFEST_FILE>

  指定一或多個 目標指令清單， 用來修剪與應用程式一起發佈的套件集。 指令清單檔是 dotnet store 指令輸出的一部分，。 若要指定多個指令清單，請為每個指令清單新增 --manifest 選項。

• --no-build

  在發佈之前不會建置專案。 它也會隱含地設定 --no-restore 旗標。

• --no-dependencies

  忽略專案對項目參考，而且只會還原根專案。

• --nologo

  不會顯示啟動橫幅或著作權訊息。

• --no-restore

  執行 命令時，不會執行隱含還原。

• -o|--output <OUTPUT_DIRECTORY>

  指定輸出目錄的路徑。

  如果未指定，它預設為 [project_file_folder]/bin/[configuration]/[framework]/publish/ 架構相依可執行檔和跨平臺二進制檔。 它預設為 [project_file_folder]/bin/[configuration]/[framework]/[runtime]/publish/ 獨立可執行檔。

  在 Web 專案中，如果輸出資料夾位於專案資料夾中，後續 dotnet publish 命令會導致巢狀輸出資料夾。 例如，如果專案資料夾 myproject，而發佈輸出資料夾 myproject/publish，而您執行 兩次，則第二次執行會將 .config 和 .json 檔案等內容檔案放在 myproject/publish/publish中。 若要避免巢狀發佈資料夾，請指定未直接 項目資料夾底下 的發行資料夾，或從專案排除發行資料夾。 若要排除名為 publishoutput的 publish 資料夾，請將下列元素新增至 PropertyGroup 檔案中的 元素：

  <DefaultItemExcludes>$(DefaultItemExcludes);publishoutput**</DefaultItemExcludes>
  

  • .NET 7.0.200 SDK 及後續版本

    如果您在解決方案上執行此命令時指定 --output 選項，CLI 會因為輸出路徑的語意不明而發出警告（7.0.200 中的錯誤）。 不允許使用 [--output] 選項，因為所有建置專案的所有輸出都會複製到指定的目錄中，這與多目標專案不相容，以及具有不同版本直接和可轉移相依性的專案。 如需詳細資訊，請參閱 解決方案層級 --output 選項對建置相關的命令不再有效。

  • .NET Core 3.x SDK 及後續版本

    如果您在發佈專案時指定相對路徑，產生的輸出目錄會相對於目前的工作目錄，而不是項目檔位置。

    如果您在發佈方案時指定相對路徑，則所有項目的輸出都會進入相對於目前工作目錄的指定資料夾。 若要讓發行輸出移至每個項目的個別資料夾，請使用 msbuild PublishDir 屬性指定相對路徑，而不是 --output 選項。 例如，dotnet publish -p:PublishDir=.\publish 將每個專案的發行輸出傳送至包含專案檔的資料夾下 publish 資料夾。

• --os <OS>

  指定目標作業系統 （OS）。 這是設定 運行時間標識碼 （RID）的速記語法，其中提供的值會與預設 RID 結合。 例如，在 win-x64 電腦上，指定 --os linux 將 RID 設定為 linux-x64。 如果您使用此選項，請勿使用 [-r|--runtime] 選項。 自 .NET 6 起可取得。

• --sc|--self-contained

  將 .NET 執行時發佈給你的應用程式，這樣就不需要在目標機器上安裝執行時。

• -p|--property:<PROPERTYNAME>=<VALUE>

  設定一或多個 MSBuild 屬性。 指定以分號分隔的多個屬性，或重複選項：

  --property:<NAME1>=<VALUE1>;<NAME2>=<VALUE2>
  --property:<NAME1>=<VALUE1> --property:<NAME2>=<VALUE2>
  

• --no-self-contained

  將你的應用程式發佈為依賴框架的應用程式。 必須在目標機器上安裝相容的 .NET 執行時才能執行您的應用程式。

• --source <SOURCE>

  還原作業期間要使用的 NuGet 套件來源 URI。

• -r|--runtime <RUNTIME_IDENTIFIER>

  發佈指定運行時間的應用程式。 如需執行時間識別碼清單（RID），請參閱 RID 目錄。 欲了解更多資訊，請參閱 .NET 應用程式發佈概覽。 如果您使用此選項，請使用 --self-contained 或 --no-self-contained。

  備註

  發佈可以在 解決方案 層級和單一 專案 層級進行。 當從解決方案層級發佈時，透過指定可選<SOLUTION>參數或保持預設，MSBuild 會先將輸出編譯到publish，且不含任何符號。 這表示 MSBuild 基於最初編譯所做的後續編譯，仍不會包含指定 <RUNTIME_IDENTIFIER>的細節。

  這是預期行為。 為了避免這種情況，你可以針對單一專案發布，指定 RID 的可選 <PROJECT> 參數，或直接在專案設定中加入 <RuntimeIdentifiers> 屬性來指定 RID。

• --tl:[auto|on|off]

  指定是否應該將 「終端機記錄器 」用於建置輸出。 默認值為 auto，這會先驗證環境，再啟用終端機記錄。 環境檢查會驗證終端機是否能夠使用新式輸出功能，而且在啟用新的記錄器之前，不會使用重新導向的標準輸出。 on 略過環境檢查，並啟用終端機記錄。 off 略過環境檢查，並使用預設的控制台記錄器。

  終端機記錄器會顯示還原階段，然後是建置階段。 在每個階段中，目前建置的專案會出現在終端機底部。 建置的每個項目都會輸出目前建置的 MSBuild 目標，以及花費在該目標上的時間量。 您可以搜尋此資訊以深入了解組建。 當專案完成建置時，會撰寫單一「已完成建置」區段來擷取：

  • 建置項目的名稱。
  • 目標架構（如果多目標）。
  • 該組建的狀態。
  • 該組建的主要輸出（已超連結）。
  • 針對該項目產生的任何診斷。

  此選項自 .NET 8 開始可用。

• --ucr|--use-current-runtime

  使用目前的執行階段作為目標執行階段。

• -v|--verbosity <LEVEL>

  設定命令的詳細資訊層級。 允許的值為 q[uiet]、m[inimal]、n[ormal]、d[etailed]與 diag[nostic]。 預設值為 minimal。 如需詳細資訊，請參閱 LoggerVerbosity。

• --version-suffix <VERSION_SUFFIX>

  定義版本後綴，以取代項目檔版本欄位中的星號 （*）。

• -?|-h|--help

  列印如何使用 命令的描述。

例子

• 為目前目錄中的專案建立 架構相依的跨平臺二進位：

  dotnet publish
  

  從 .NET Core 3.0 SDK 開始，這個範例也為目前平台建立一個依賴於 framework 依賴的執行檔。

• 針對特定運行時間，為目前目錄中的專案建立 獨立可執行檔：

  dotnet publish --runtime osx-x64
  

  RID 必須位於項目檔中。

• 針對特定平臺，為目前目錄中的專案建立 架構相依的可執行檔：

  dotnet publish --runtime osx-x64 --self-contained false
  

  RID 必須位於項目檔中。 此範例適用於 .NET Core 3.0 SDK 及後續版本。

• 針對特定運行時間和目標架構，發佈目前目錄中的專案：

  dotnet publish --framework net8.0 --runtime osx-x64
  

• 發佈指定的項目檔：

  dotnet publish ~/projects/app1/app1.csproj
  

• 發佈目前的應用程式，但不還原專案對專案 （P2P） 參考，只是還原作業期間的根專案：

  dotnet publish --no-dependencies
  

• 將檔案型 C# 程式 app.cs 發佈在目前目錄中：

  dotnet publish app.cs
  

  檔案式程式支援則在 .NET SDK 10.0.100 中加入。

另請參閱

• .NET 應用程式發佈概述
• 目標架構
• 執行時間識別碼 （RID） 目錄
• 用dotnet publish
• 使用 macOS Catalina Notarization
• 已發佈應用程式的目錄結構
• MSBuild 命令行參考
• Visual Studio 發佈 profiles （.pubxml） for the app deployment for ASP.NET Core app
• dotnet MSbuild
• 修剪獨立式部署