dotnet publish

本文適用於： ✔️ .NET Core 3.1 SDK 與更新版本

名稱

dotnet publish：將應用程式與其相依性發行至資料夾中，以部署至主機系統。

概要

dotnet publish [<PROJECT>|<SOLUTION>] [-a|--arch <ARCHITECTURE>]
    [-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>] [-r|--runtime <RUNTIME_IDENTIFIER>]
    [--sc|--self-contained [true|false]] [--no-self-contained]
    [-s|--source <SOURCE>] [--tl:[auto|on|off]]
    [--use-current-runtime, --ucr [true|false]]
    [-v|--verbosity <LEVEL>] [--version-suffix <VERSION_SUFFIX>]

dotnet publish -h|--help

描述

dotnet publish 會編譯應用程式，讀取在其專案檔中指定的相依性，然後將產生的一組檔案發行到目錄中。 此輸出包含下列資產：

• 組件中的中繼語言 (IL) 程式碼，副檔名為 dll。
• 包含專案所有相依性的 .deps.json檔案。
• .runtime.config.json 檔案，此檔案會指定應用程式預期的共用執行階段，以及執行階段的其他設定選項 (例如記憶體回收類型)。
• 應用程式的相依性，這些相依性會從 NuGet 快取複製到輸出資料夾。

dotnet publish　命令的輸出已準備好部署到裝載系統 (例如伺服器、電腦、Mac、膝上型電腦) 以供執行。 這是準備應用程式以供部署的唯一正式支援的方法。 根據專案指定的部署類型，主機系統上可能有已安裝 (或未安裝)的 .NET 共用執行階段。 如需詳細資訊，請參閱使用 .NET CLI 發佈 .NET 應用程式。

隱含還原

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

dotnet restore 命令在適合進行明確還原的特定案例中仍可派上用場，例如 Azure DevOps Services 中的持續整合組建，或在需要明確控制何時進行還原的組建系統中。

如需了解如何管理 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。 舉例來說，您可以使用 -p:<NAME>=<VALUE> 格式設定 MSBuild 屬性。

.pubxml 檔案

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

dotnet publish -p:PublishProfile=FolderProfile

上述範例使用位於 <project_folder>/Properties/PublishProfiles 資料夾中的 FolderProfile.pubxml 檔案。 若在設定 PublishProfile 屬性時指定了路徑和副檔名，系統會忽視這兩者。 根據預設，MSBuild 會查看 Properties/PublishProfiles 資料夾，並採用 pubxml 副檔名。 若需指定路徑和包括副檔名在內的檔案名稱，請不要設定 PublishProfile 屬性，改為設定 PublishProfileFullPath 屬性。

在 .pubxml 檔案中：

• Visual Studio 會使用 PublishUrl 表示發行目標。
• 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 不支援的 .pubxml 屬性中，請特別注意下列會影響組件的屬性：

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

MSBuild 屬性

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

• PublishReadyToRun

  將應用程式組件編譯為 ReadyToRun (R2R) 格式。 R2R 是一種預先(AOT) 編譯。 如需詳細資訊，請參閱 ReadyToRun 映像。

  若要查看可能導致執行階段失敗的遺漏相依性警告，請使用 PublishReadyToRunShowWarnings=true。

  建議您在發行設定檔中指定 PublishReadyToRun，而不要在命令列上指定。

• PublishSingleFile

  將應用程式封裝成平台特定的單一檔案可執行檔。 如需單一檔案發佈的詳細資訊，請參閱單一檔案搭配程式設計文件。

  建議您在專案檔中指定此選項，而不要在命令列上指定。

• PublishTrimmed

  發行獨立式可執行檔時，請修剪未使用的程式庫以減少應用程式的部署大小。 如需詳細資訊，請參閱修剪獨立式部署及可執行檔。 自 .NET 6 SDK 起提供使用。

  建議您在專案檔中指定此選項，而不要在命令列上指定。

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

• MSBuild 命令列參考
• 適用於 ASP.NET Core 應用程式部署的 Visual Studio 發行設定檔 (.pubxml)
• dotnet msbuild

工作負載資訊清單下載

執行此命令會啟動工作負載公告資訊清單的非同步背景下載。 若此命令完成時下載仍在執行，則會停止下載。 如需詳細資訊，請參閱廣告資訊清單。

引數

• PROJECT|SOLUTION

  要發佈的專案或解決方案。

  • PROJECT 是 C#、F# 或 Visual Basic 專案檔的路徑與檔案名稱，或包含 C#、F# 或 Visual Basic 專案檔的目錄路徑。 如未指定目錄，系統會將其預設為當前的目錄。

  • SOLUTION 為解決方案檔案的路徑和檔案名稱 (副檔名為 .sln)，或為包含解決方案之目錄的路徑。 如未指定目錄，系統會將其預設為當前的目錄。

選項。

• -a|--arch <ARCHITECTURE>

  指定目標結構。 這是用於設定執行階段識別碼 (RID) 的速記語法，其中提供的值會與預設 RID 合併。 例如在 win-x64 機器上，指定 --arch x86 將 RID 設定為 win-x86。 若使用此選項，請勿使用 -r|--runtime 選項。 自 .NET 6 Preview 7 起提供使用。

• -c|--configuration <CONFIGURATION>

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

• --disable-build-servers

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

• -f|--framework <FRAMEWORK>

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

• --force

  即使最後的還原成功，仍強制解析所有相依性。 指定這個旗標等同於刪除 project.assets.json 檔案。

• -?|-h|--help

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

• --interactive

  可讓命令停止，並等候使用者輸入或進行動作。 例如完成驗證。 自 .NET Core 3.0 SDK 起提供使用。

• --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」，而您執行 dotnet publish 兩次，第二次執行會將 .config 與 .json 檔案等內容檔案放在 myproject/publish/publish。 若要避免出現巢狀發佈資料夾，請指定並非直接位於專案資料夾底下的發佈資料夾，或者將發佈資料夾從專案中排除。 若要排除名為 [publishoutput] 的發行資料夾，請將下列元素新增至 .csproj 檔案中的 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 資料夾。

  • .NET Core 2.x SDK

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

    如果您在發行解決方案時指定了相對路徑，則每項專案的輸出會進入相對於專案檔位置的個別目錄。 如果您在發行解決方案時指定了絕對路徑，則所有專案的一切發行輸出都會進入指定資料夾。

• --os <OS>

  指定目標作業系統 (OS)。 這是用於設定執行階段識別碼 (RID) 的速記語法，其中提供的值會與預設 RID 合併。 例如在 win-x64 機器上，指定 --os linux 將 RID 設定為 linux-x64。 若使用此選項，請勿使用 -r|--runtime 選項。 自 .NET 6 起提供使用。

• --sc|--self-contained [true|false]

  使用您的應用程式發佈 .NET 執行階段，如此即無須在目標機器上安裝執行階段。 若已指定執行階段識別碼，且專案為可執行檔專案 (而非程式庫專案)，則預設值為 true。 如需詳細資訊，請參閱 .NET 應用程式發佈和使用 .NET CLI 發佈 .NET 應用程式。

  若使用此選項時沒有指定 true 或 false，則預設值為 true。 在此情況下，請勿在 --self-contained 之後立即放置解決方案或專案引數，因為那是 true 或 false 的放置位置。

• --no-self-contained

  相當於 --self-contained false。

• --source <SOURCE>

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

• -r|--runtime <RUNTIME_IDENTIFIER>

  發行所指定執行階段的應用程式。 如需執行階段識別項 (RID) 清單，請參閱 RID 目錄。 如需詳細資訊，請參閱 .NET 應用程式發佈和使用 .NET CLI 發佈 .NET 應用程式。 如果您採用此選項，也請使用 --self-contained 或 --no-self-contained。

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

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

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

  • 所建置專案的名稱。
  • 目標架構 (如果為多目標)。
  • 該組建的狀態。
  • 該組建的主要輸出 (已有超連結)。
  • 任何針對該專案產生的診斷。

  此選項從 .NET 8 開始提供使用。

• --use-current-runtime, --ucr [true|false]

  在其中一台機器上，將 RuntimeIdentifier 設定為平台可攜 RuntimeIdentifier。 這會與需要 RuntimeIdentifier 的屬性 (例如 SelfContained、PublishAot、PublishSelfContained、PublishSingleFile 與 PublishReadyToRun) 一起隱含執行。 若此屬性設為 False，隱含解析就再也不會執行。

• -v|--verbosity <LEVEL>

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

• --version-suffix <VERSION_SUFFIX>

  定義要取代專案檔案的版本欄位中之星號 (*) 的版本尾碼。

範例

• 為當前目錄中的專案建立架構獨立的跨平台二進位檔：

  dotnet publish
  

  自 .NET Core 3.0 SDK 起，此範例也會為目前的平台建立架構相依可執行檔。

• 針對特定執行階段，為當前目錄中的專案建立獨立式可執行檔：

  dotnet publish --runtime osx-x64
  

  RID 必須位於專案檔中。

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

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

  RID 必須位於專案檔中。 此範例適用於 .NET Core 3.0 SDK 和更新版本。

• 針對特定執行階段和目標 Framework，在當前目錄中發行專案：

  dotnet publish --framework netcoreapp3.1 --runtime osx-x64
  

• 發行指定的專案檔：

  dotnet publish ~/projects/app1/app1.csproj
  

• 發行目前的應用程式，但不還原專案對專案 (P2P) 參考，還原作業期間僅還原根專案：

  dotnet publish --no-dependencies
  

另請參閱

• .NET 應用程式發佈概觀
• 使用 .NET CLI 發佈 .NET 應用程式
• 目標架構
• 執行階段識別碼 (RID) 目錄
• 使用 dotnet publish 將 .NET 應用程式容器化
• 使用 macOS Catalina Notarization
• 已發行應用程式的目錄結構
• MSBuild 命令列參考
• 適用於 ASP.NET Core 應用程式部署的 Visual Studio 發行設定檔 (.pubxml)
• dotnet msbuild
• 修剪自封式部署