如何高效在美國 Windows 伺服器上配置 SSR

你可以透過在 美國 Windows 伺服器 上結合 IIS（含 httpPlatformHandler 模組）與 Node.js 來高效部署 SSR。在開始之前，請確認你已具備以下前置條件：

• 已安裝並完成基礎設定的 Windows Server

• 伺服器上已安裝並執行 IIS

• 已為 Angular SSR 專案安裝並設定好 Node.js

• 已準備好支援伺服端渲染的全部 Angular 應用程式檔案

像 Angular Universal SSR 和 Vite 這類框架，可以顯著提升 Angular 應用程式的效能與 SEO 表現。透過升級 Angular、為 SSR 重構程式碼，並確保伺服端與用戶端正確 Hydration，可以有效改善首屏載入時間與搜尋引擎排名。

關鍵重點

• 先準備好環境：安裝 Windows Server，啟用 IIS，並準備好用於 SSR 的 Angular 應用程式檔案。

• 使用 httpPlatformHandler 將 IIS 與 Node.js SSR 應用程式串接起來，以獲得更好的行程管理與可擴充性。

• 在 wwwroot 資料夾中妥善組織 SSR 檔案，協助 IIS 快速定位資源並維持結構清晰。

• 正確設定 web.config 檔案，明確告訴 IIS 如何處理請求並啟動 SSR 行程。

• 定期檢視 IIS 與 Node.js 日誌，進行問題排查，確保 SSR 應用程式長期穩定運行。

配置 SSR 前的準備工作

在美國 Windows 伺服器上部署 SSR 之前，需要先確保環境與專案檔案都已準備就緒。以下檢查清單可以幫助你順利完成前期準備：

• 已安裝並更新完成的 Windows Server

• 已啟用並執行的 IIS（Windows IIS）

• 已下載並安裝的 Node.js

• 已打包完成、可用於部署的 Angular 應用程式檔案

• 選定的 SSR 框架（如 Angular Universal 或 Vite）

Windows Server 與 IIS 設定

首先應確認 Windows IIS 已在伺服器上正常啟用。開啟「伺服器管理員」，檢查「角色與功能」。確保已安裝 Application Request Routing（ARR）和 URL Rewrite。這些功能有助於為 SSR 應用程式轉送請求並管理流量。還需要在部署目錄中建立一個 logs 資料夾，並為應用程式集區身分賦予寫入權限，以便 IIS 能夠寫入日誌，方便後續除錯。

同時建議從 web.config 中移除 WebDAV 模組與處理常式，以避免產生 HTTP 405 錯誤。如果沒有使用 WebDAV Publishing，最好將其停用，以提升伺服器安全性。

Node.js 安裝

在 Windows 上安裝 Node.js 時，通常需要搭配 iisnode 模組一併使用。該模組是 Windows IIS 環境下特有的元件，提供行程管理、可擴充性以及與 IIS 的便捷整合。有了 iisnode，你可以管理多個 Node.js 行程，在更新後回收行程，並透過日誌進行除錯。一般不需要對 Angular SSR 應用程式程式碼做太多修改，就可以利用 IIS 管理工具對整體部署進行控制。

SSR 應用程式檔案組織

在 Windows IIS 環境中，需要妥善規劃 SSR 檔案結構。將靜態資源放在 wwwroot 資料夾中；把主要伺服端入口檔案（例如 Program.cs）放在專案根目錄；將 appsettings.json 和 appsettings.Development.json 等設定檔放在同一位置。這樣的結構有助於 IIS 快速查找相關檔案，並維持部署目錄清晰易於維護。

提示：Angular Universal 提供生產級的 SSR 能力，包括串流渲染與預先渲染等特性；而 Vite（特別是搭配 Nuxt 3）則提供輕量、快速的開發體驗。可以依據專案需求在兩者之間做選擇。

完成以上準備工作後，你就可以更有信心地在 Windows IIS 環境下，結合 Node.js 與 Angular 應用程式來建置 SSR。

為 SSR 安裝 httpPlatformHandler

在 Windows IIS 上部署伺服端渲染，需要安裝 httpPlatformHandler。該模組扮演 IIS 與 Node.js SSR 應用程式之間的橋樑。你只需依照幾個清楚的步驟完成安裝與設定，即可讓兩者順利協同運作。

下載並安裝模組

在 IIS 上執行 SSR 應用程式之前，需要先下載並安裝最新版的 httpPlatformHandler 模組。可依照以下步驟操作：

1. 在一般 Windows 電腦上造訪微軟官方網站，下載最新的 x64 版本 httpPlatformHandler 安裝包。

2. 安裝完成後，找到以下檔案：

   • %windir%\System32\inetsrv\httpPlatformHandler.dll

   • %windir%\System32\inetsrv\config\schema\httpplatform_schema.xml

3. 將上述檔案複製到目標伺服器。如果使用 Nano Server，可以透過 PowerShell 或遠端工作階段傳輸檔案。

4. 在目標伺服器上，使用 PowerShell 執行以下指令，將檔案放入正確目錄：

   copy .\httpPlatformHandler.dll C:\Windows\System32\inetsrv
   copy .\httpplatform_schema.xml C:\Windows\System32\inetsrv\config\schema
   

5. 在 IIS 中啟用 httpPlatformHandler。開啟 IIS 管理員，進入「模組（Modules）」頁面，確認清單中已經出現 httpPlatformHandler。

提示：務必下載與伺服器硬體架構相符的版本。架構不相符往往會導致模組載入失敗。

相容性問題

在不同版本的 Windows Server 上使用 httpPlatformHandler 時，可能會遇到一些相容性問題。下表列出了常見問題及其影響：

• HttpPlatformHandler v1.2 存在多項限制與錯誤，會影響效能表現。

• 已知問題包含無法關閉的 8 KB 輸出快取，以及在 Windows ARM64 上出現的應用程式集區當機。

• 如果你使用 Server-Sent Events 或 Socket.IO 等特性，安裝完成後務必對 SSR 應用程式進行充分測試。

設定處理常式對應（Handler Mapping）

安裝好 httpPlatformHandler 之後，還需要在 IIS 中設定處理常式對應。該設定用來指示 IIS 將所有進入的請求轉送給 Node.js SSR 行程。

• 開啟網站根目錄下的 web.config 檔案。

• 在 <handlers> 節點中加入以下設定行：

  <add name="SSR" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
  

• 確保 <httpPlatform> 節點中包含以下屬性：

  • stdoutLogEnabled

  • stdoutLogFile

  • startupTimeLimit

  • processPath

  • arguments

注意：正確的處理常式對應可確保 IIS 將每一次請求都轉送給你的 SSR 伺服端，從而實現無縫的伺服端渲染體驗。

完成以上步驟後，你已經在 Windows IIS 伺服器上為 SSR 配置好了 httpPlatformHandler，接下來可以進一步進行更進階的 SSR 設定與疑難排解。

在 IIS 中設定 SSR

在 IIS 中完成伺服端渲染設定，是部署成功的關鍵一步。你需要特別關注以下三個面向：設定 processPath 與 arguments、新增環境變數，以及撰寫可靠的 web.config 檔案。每一個部分都在確保 Angular SSR 應用程式能在 Windows 伺服器上平穩運行方面扮演重要角色。

設定 processPath 與 arguments

首先要告訴 IIS 如何啟動 SSR 行程。processPath 指向 Node.js 執行檔，而 arguments 則指定要執行的 Angular Universal SSR 入口檔案。透過這兩項設定，httpPlatformHandler 才能在每次收到請求時正確啟動並執行你的伺服端渲染程式碼。

• 將 processPath 設定為 node，用來指示 IIS 透過 Node.js 來執行應用程式。

• 使用 arguments 指向主要伺服端檔案。例如，對 Angular Universal 而言，參數可以是 ./dist/angular-ssr/server/server.mjs。

• 確保該路徑與目前專案結構一致。如果移動了檔案，記得同步更新設定中的 arguments。

提示：務必要反覆確認 processPath 與 arguments 是否正確填寫，一個小小的拼寫錯誤就可能導致 Angular 應用程式無法啟動。保持這兩項設定精確無誤，可以讓 httpPlatformHandler 穩定找到並執行你的 SSR 程式碼。

新增環境變數

環境變數有助於讓 SSR 應用程式依據不同情境做出相應行為。你可以在 web.config 檔案的 httpPlatform 節點下進行設定。合理設計環境變數，不僅能提升伺服端渲染的彈性，也有助於整體安全性。

以下是在 IIS 上執行 SSR 應用程式時，幾個最重要的環境變數：

你也可以視需求額外加入：

• SCM_DO_BUILD_DURING_DEPLOYMENT：若希望在部署時由 IIS 觸發建置流程，可將其設為 true。

注意：切勿在專案程式碼或設定檔內直接存放敏感環境變數，尤其是在生產環境。請使用安全的驗證流程，並在本機開發時搭配 Secret Manager 等工具。如果是部署在 Azure，可利用受控身分識別（Managed Identity）來避免明文存放認證資訊。

範例 web.config

結構清晰的 web.config 是整個 SSR 設定的「核心」。它負責告訴 IIS 如何處理請求、如何啟動 SSR 行程，以及如何寫入日誌。以下是一個搭配 httpPlatformHandler 的 Angular Universal SSR 應用程式範例設定：

<configuration>
  <system.webServer>
    <handlers>
      <add name="httpPlatformHandler" path="*" verb="*" modules="httpPlatformHandler" />
    </handlers>
    <httpPlatform 
      processPath="node"
      arguments="./dist/angular-ssr/server/server.mjs"
      startupTimeLimit="20"
      startupRetryCount="2"
      stdoutLogEnabled="true"
      stdoutLogFile="./log.txt">
      <environmentVariables>
        <environmentVariable name="PORT" value="%HTTP_PLATFORM_PORT%" />
        <environmentVariable name="NODE_ENV" value="production" />
      </environmentVariables>
    </httpPlatform>
  </system.webServer>
</configuration>

以下對關鍵設定做一個簡要說明：

• handlers 節點確保 IIS 對所有請求都使用 httpPlatformHandler 進行處理。

• processPath 與 arguments 告訴 IIS 如何啟動 SSR 伺服端。

• environmentVariables 節點為 Angular Universal 應用程式設定 PORT 與 NODE_ENV。

• 日誌檔能夠記錄 SSR 行程輸出，方便你在發生問題時進行除錯。

提示：務必保持設定檔結構清楚，每次修改 web.config 之後都要仔細檢查，避免低階錯誤。乾淨有序的設定不僅有利於初次建置 SSR，也有助於後續的疑難排解與維護。

透過以上設定，你就為 SSR 部署奠定了穩固基礎：一方面向 IIS 提供明確指令，另一方面兼顧環境安全與執行效率，讓 Angular Universal SSR 應用程式得以在 Windows 伺服器上高效運作。

排查伺服端渲染問題

在 IIS 與 Node.js 搭配使用時，伺服端渲染的部署過程可能相對複雜，你在建置與上線過程中很可能會遇到各式各樣的問題。本章節將協助你辨識並解決最常見的故障，確保 Angular SSR 應用程式維持穩定。

IIS 與 Node.js 相關問題

當 IIS 嘗試處理 Node.js 應用程式時，你可能會看到以下類型的錯誤：

• iisnode 在處理請求時發生錯誤，頁面上可能會顯示具體的 HRESULT 與 HTTP 狀態碼。

• 若 Application Insights 將 maxBatchIntervalMs 保持預設值 15000ms，可能導致回應變慢，進而影響 HTTP 請求效能。

• 內部伺服器錯誤（例如 HRESULT: 0x2 與 HTTP 狀態碼 500）通常指向設定錯誤或權限問題。

你可以透過調整部分設定來改善除錯體驗與可靠性。下表列出了一些常用設定及其說明：

提示：出現問題時，一定要同時查看 IIS 日誌與 Node.js 日誌。詳細的錯誤資訊往往隱藏在日誌中，可以協助你快速定位根本原因。

SSR 啟動錯誤

啟動階段的錯誤可能會在 SSR 真正執行前就中斷整個流程。你可能會看到「HTTP Error 503: The service is unavailable」這類訊息，或是關於缺少設定檔的錯誤，有時服務會持續嘗試重新啟動卻始終無法成功。

常見的啟動錯誤包括：

可以依照以下步驟進行排查與修復：

1. 按下「Win + R」開啟「執行」，輸入「services.msc」並按下 Enter，開啟「服務」主控台。

2. 找到發生錯誤的服務，按右鍵並選擇「內容」。

3. 切換到「登入」索引標籤，選擇「此帳戶」，並輸入系統管理員憑證。

4. 按一下「套用」，再按「確定」。重新啟動電腦後檢查該服務是否能正常啟動。

5. 若問題仍然存在，切換到「相依性」索引標籤，確認所有相依服務都已啟動。

注意：許多啟動錯誤往往源自缺少檔案或權限設定錯誤。請再次檢查設定檔與路徑的正確性。

環境變數問題

在部署 Angular Universal 時，環境變數扮演關鍵角色。一旦設定不當，應用程式可能無法啟動或出現無法預期的行為。你應當區分執行階段環境變數與用戶端環境變數，並將敏感資訊自程式碼中抽離。建議使用 Azure Key Vault 或 GitHub secrets 等工具儲存機密資訊，再透過 CI/CD 流程在建置階段產生 .env 檔案，以確保各環境間的變數保持同步。

整體而言，在建置階段產生環境變數檔，是既安全又高效的做法：既能保護敏感資料，又能確保每次部署時 Angular 應用程式都擁有正確設定。

記住：在所有環境中維持環境變數一致，是避免隱性錯誤、確保 SSR 部署安全穩定的關鍵。

透過在美國 Windows 伺服器上結合 IIS 與 httpPlatformHandler 部署 SSR，你可以顯著提升首屏載入速度並改善 SEO。對於 Angular SSR 應用程式而言，預先渲染能帶來更佳的使用者體驗，尤其是在採用 Angular Universal 或 Vite 的情況下。上述步驟式指南幫助你在兼顧可靠性的前提下，簡化 Angular 的部署流程。在進行長期維運時，還應特別關注下列幾個面向：

只要遵循以上步驟，你就能為 SSR 部署打下穩固基礎。

常見問題（FAQ）

在 SSR 中，將 IIS 與 httpPlatformHandler 一起使用的主要優勢是什麼？

最大的優點是能在 Windows Server 與 Node.js 之間建立無縫整合。IIS 負責行程管理、請求處理與日誌記錄，從而提升整體穩定性，並簡化 SSR 應用程式的部署流程。

在 Windows 上部署 SSR 時，除了 Angular Universal 還能使用其他框架嗎？

當然可以！你可以使用例如 Vite 或 Next.js 等框架，只要它們的 SSR 入口檔能透過 Node.js 與 httpPlatformHandler 正常運作即可。上線前務必確認框架與目前部署環境的相容性。

如何在不影響線上使用者的情況下升級 Node.js 或 SSR 應用程式？

可以透過回收 IIS 應用程式集區，或使用零停機部署（Zero-Downtime Deployment）工具來達成。如此一來，你可以在更新 Node.js 或 SSR 檔案的同時，盡量維持網站對使用者的可用性。

為什麼 SSR 應用程式在部署後出現空白頁？

• web.config 中的 processPath 或 arguments 可能設定錯誤。

• 缺少必要的環境變數也可能導致空白頁問題。

• 請檢查 IIS 與 Node.js 日誌，以找出具體錯誤資訊。