本文適合第一次執行 v2rayN 的 Windows 與 macOS 使用者。內容涵蓋安裝包選擇、目錄解壓縮、執行環境、核心檢查、中文介面、本機連接埠、訂閱匯入與系統代理，並提供首次啟動錯誤的處理方式。完成後應能確認用戶端、核心、節點與系統代理各自的狀態。
安裝前先確認系統架構與檔案位置
先在系統資訊中確認處理器架構，再選擇對應的安裝包。Windows 常見選擇為 x64，採用 ARM 處理器的裝置則選擇 arm64。macOS 裝置同樣需要區分 x64 與 arm64；架構選錯時，程式可能無法啟動，或透過相容層執行而增加資源占用。
Windows 不要直接在壓縮檔預覽視窗中執行主程式。請先將所有檔案解壓縮到固定目錄，例如使用者目錄下的 Applications\v2rayN。v2rayN 的設定、資料庫與核心檔案之間存在相對路徑關係，只單獨拖出主程式會導致核心檢查失敗。
目錄應允許目前帳戶寫入。不要長期將程式放在暫存下載目錄，也不要放入必須具備管理員權限才能修改的系統目錄。首次退出時，用戶端需要儲存介面語言、本機連接埠、訂閱群組與路由設定；寫入失敗會表現為重新啟動後設定恢復預設值。
解壓縮後要檢查哪些檔案
- 確認主程式與其餘目錄位於同一層級，不要只複製一個可執行檔。
- 確認磁碟至少保留 300 MB 可用空間，後續更新核心與路由資料庫時仍會寫入新檔案。
- 確認目錄名稱中沒有異常控制字元。一般中文、英文、數字與空格通常都能正常使用。
- 如果是從舊版本遷移，請先保留舊目錄，不要立即覆蓋。首次啟動成功後，再依需求遷移設定。
Windows 與 macOS 的首次啟動順序
Windows 端先雙擊 v2rayN 主程式。如果系統提示缺少桌面執行環境，請記下提示中的主版本與架構，再安裝對應的 .NET Desktop Runtime。x64 程式應搭配 x64 執行環境；只安裝其他架構版本通常無法解決啟動問題。
程式啟動後可能只顯示在系統匣區域。請先檢查工作列通知區域，再判斷是否啟動失敗。雙擊系統匣圖示可開啟主視窗，按右鍵則可切換系統代理、路由模式與目前節點。
- 解壓縮完整目錄，並確認目前帳戶具備讀取與寫入權限。
- 啟動主程式，等待 10 至 20 秒，讓用戶端完成設定目錄與日誌初始化。
- 開啟主視窗，進入「設定」→「參數設定」，檢查語言與本機監聽連接埠。
- 開啟日誌區域，確認沒有持續重複的紅色啟動錯誤。
- 匯入一個有效設定，執行延遲測試後再開啟系統代理。
macOS 首次開啟的處理方式
macOS 端先將應用程式移至固定的應用程式目錄，再從 Finder 開啟。首次執行出現來源確認提示時，進入「系統設定」→「隱私權與安全性」，核對遭阻擋的應用程式名稱，然後使用系統提供的再次開啟入口。不要因為權限提示而反覆解壓縮多個副本，否則後續很難判斷實際啟動的是哪一份程式。
如果系統提示應用程式沒有執行權限，請先確認下載與解壓縮過程是否完整。使用圖形化解壓縮工具重新展開原始壓縮檔，通常比直接修改整個目錄的權限更穩妥。程式可以開啟但無法儲存設定時，則檢查應用程式資料目錄是否由目前帳戶擁有。
檢查用戶端、核心與節點三層狀態
v2rayN 是設定與系統代理管理介面，實際連線由所選核心處理。主視窗能夠開啟，只能表示用戶端介面已啟動；這不代表核心已成功執行，也不代表節點可以連線。排查時必須將這三個層級分開檢查。
先進入「設定」→「參數設定」→「核心設定」，確認設定類型對應的核心。VLESS、VMess 等設定通常可交由 Xray 核心處理。接著選擇一個節點並設為活動伺服器，觀察日誌中是否產生本機監聽位址與輸出連線記錄。
| 檢查層級 | 正常現象 | 異常時先檢查 |
|---|---|---|
| 用戶端介面 | 主視窗或系統匣圖示可操作，設定可以儲存 | 執行環境、目錄寫入權限、重複程序 |
| 代理核心 | 日誌顯示本機連接埠開始監聽，沒有反覆退出 | 核心檔案、設定語法、連接埠占用 |
| 遠端節點 | 延遲測試返回數值，連線日誌出現輸出記錄 | 位址、連接埠、協定參數、網路可達性 |
| 系統代理 | 瀏覽器請求進入 v2rayN 的本機監聽連接埠 | 系統代理開關、瀏覽器獨立代理、繞過規則 |
結論：先確認本機監聽，再測試遠端連線
日誌中沒有出現 127.0.0.1 的監聽連接埠時，修改瀏覽器或訂閱參數沒有意義。先解決核心啟動與連接埠占用，再檢查節點協定與遠端位址。
設定介面語言、本機連接埠與開機行為
開啟「設定」→「參數設定」→「v2rayN 設定」，將語言切換為繁體中文。部分 7.x 小版本會在重新啟動介面後完整套用語言變更。修改後先正常退出用戶端，再重新啟動，不要直接結束程序。
本機連接埠供應用程式連線至 v2rayN。常見設定以 10808 作為 SOCKS 入口，以 10809 作為 HTTP 入口；實際數值以目前「參數設定」中顯示的內容為準。連接埠可以變更，但同一台裝置上的兩個程式不能同時監聽相同的位址與連接埠。
如果瀏覽器使用系統代理，就不需要另外填寫 SOCKS 位址。只有命令列工具、開發工具或不讀取系統代理的程式，才需要手動指定 127.0.0.1 與對應連接埠。手動填寫時要區分 SOCKS 與 HTTP 類型。
| 設定項目 | 建議初始值 | 修改條件 |
|---|---|---|
| 監聽位址 | 127.0.0.1 | 僅供本機使用時維持本機迴路位址 |
| SOCKS 連接埠 | 10808 | 日誌明確提示該連接埠已被占用時更換 |
| HTTP 連接埠 | 10809 | 外部工具已使用該連接埠時更換 |
| 開機啟動 | 首次除錯階段關閉 | 連續完成數次正常啟動後再開啟 |
| 自動更新訂閱 | 先手動更新 | 確認群組位址與更新方式正確後啟用 |
匯入訂閱並完成第一次連線測試
進入「訂閱群組」→「訂閱群組設定」，建立新群組並貼上服務商提供的訂閱位址。群組名稱用於本機識別，可依用途填寫。儲存後回到主介面，執行「訂閱群組」→「更新全部訂閱（不透過代理）」。
首次更新通常不應依賴尚未驗證的代理節點。如果目前網路無法直接取得訂閱，再選擇透過代理更新，但前提是清單中已存在可正常運作的設定。更新完成後檢查節點數量與協定類型，不要只看「更新成功」提示。
- 選擇一個節點，使用右鍵選單將其設為活動伺服器。
- 執行延遲測試，確認結果不是逾時或空值。延遲數值只表示測試鏈路可達，不代表所有網站都能正常存取。
- 在系統匣選單中選擇「系統代理」→「自動設定系統代理」。
- 維持預設路由模式完成基礎測試，暫時不要疊加複雜的自訂規則。
- 開啟瀏覽器造訪常用頁面，同時觀察日誌中是否出現對應連線。
- 測試完成後，再決定是否啟用繞過中國大陸或其他路由規則。
VMess 與 VLESS 是節點協定，不是系統代理模式。系統代理負責將應用程式流量送至本機連接埠，路由規則決定請求走代理或直連，協定參數則決定核心如何連線至遠端伺服器。三個概念不能互相取代。
結論：首次測試維持單一節點與預設路由
先使用一個已知有效的節點完成「訂閱更新、延遲測試、系統代理、網頁存取」閉環，再新增自訂 DNS 與分流規則。一次修改多個層級，會讓日誌難以對應具體原因。
首次啟動常見錯誤與處理方式
處理錯誤時先查看導致核心退出的第一筆記錄，不要只看後續出現的連線失敗。日誌常會產生連鎖提示：執行環境缺失會導致主程式退出，連接埠占用會導致核心退出，核心退出又會讓瀏覽器顯示代理伺服器沒有回應。
錯誤：You must install or update .NET to run this application.
原因與解法：目前系統缺少程式要求的 .NET Desktop Runtime，或執行環境架構不相容。依提示安裝對應的主版本與 x64、arm64 架構，完成後重新啟動 v2rayN。
錯誤：A fatal error occurred. The required library hostfxr.dll could not be found.
原因與解法：執行環境檔案缺失，或只複製了主程式而沒有保留完整目錄。重新解壓縮完整安裝包；使用依賴執行環境的版本時，再修復對應的 .NET Desktop Runtime。
錯誤：failed to start listener: bind: address already in use
原因與解法：10808、10809 或目前設定的監聽連接埠已被其他程序占用。退出重複的 v2rayN 執行個體，或在「設定」→「參數設定」中更換連接埠，然後重新啟動核心。
錯誤：failed to find an available destination
原因與解法：遠端位址解析失敗、節點參數無效，或目前網路無法連線至目標。檢查伺服器位址與連接埠，重新整理 DNS 狀態，再透過日誌確認是否仍在同一目標上失敗。
提示：無法開啟「v2rayN」，因為無法驗證開發者
原因與解法：macOS 阻止了首次開啟。確認應用程式來源與檔案名稱後，進入「系統設定」→「隱私權與安全性」，使用系統顯示的再次開啟選項，並依提示完成確認。
現象：設定儲存後重新啟動又恢復預設值
原因與解法：程式目錄或應用程式資料目錄不可寫入，也可能是程序被強制結束。將程式移至目前帳戶可寫入的位置，正常退出一次，再檢查設定檔的更新時間。
日誌應保留哪些資訊
- 保留錯誤發生前後約 20 行，以便確認第一筆失敗記錄。
- 記錄 v2rayN 主版本、系統版本與處理器架構。
- 記錄目前核心類型、本機監聽連接埠與錯誤發生時間。
- 分享日誌前，刪除訂閱位址、節點網域、使用者識別資訊與驗證資訊。
首次設定常見問題
以下問題多出現在用戶端已經開啟、但連線鏈路尚未完整建立的階段。處理順序仍是本機監聽、活動節點、系統代理、路由規則，逐層確認。
關閉視窗後為什麼還在執行？
v2rayN 通常會縮小至系統匣繼續運作。需要完全退出時，請在系統匣圖示上按右鍵並選擇「退出」。只關閉主視窗不會停止核心，也不會自動撤銷目前的系統代理。
訂閱更新成功，為什麼節點清單仍然是空的？
開啟「訂閱群組」→「訂閱群組設定」，確認更新的是目前群組，並檢查群組篩選條件。接著重新執行更新，觀察日誌中解析出的設定數量是否為 0。
延遲有數值，瀏覽器為什麼仍然無法開啟頁面？
先檢查系統匣中的系統代理是否為「自動設定系統代理」，再確認瀏覽器沒有另外覆寫代理設定。接著查看造訪頁面時日誌是否產生連線記錄；沒有記錄通常表示流量未進入本機連接埠。
10808 被占用，可以直接改成其他連接埠嗎？
可以。進入「設定」→「參數設定」改用未占用的連接埠，例如 10818，儲存後重新啟動核心。命令列工具與其他手動代理應用程式也要同步改用新連接埠。
每次開機都要重新選擇節點嗎？
正常退出時，v2rayN 會儲存活動伺服器。如果每次都恢復預設值，請先檢查設定目錄的寫入權限；確認儲存正常後，再到參數設定中啟用開機啟動。
完成初始化後的驗收清單
首次安裝結束前，進行一次完整驗收。不要只以主視窗能夠開啟作為成功標準。用戶端應能儲存設定，核心應穩定監聽本機連接埠，活動節點應產生有效的輸出記錄，系統代理也應能正常開啟與撤銷。
- 重新啟動 v2rayN 後，介面語言、訂閱群組與本機連接埠仍維持原值。
- 日誌中能看到核心啟動與本機監聽記錄，沒有反覆退出的循環。
- 活動節點的協定、位址、連接埠與服務商提供的資訊一致。
- 開啟系統代理後，瀏覽器請求會進入日誌；關閉後，系統代理設定能夠恢復。
- 10808、10809 或自訂連接埠沒有被第二個用戶端執行個體占用。
- Windows 的執行環境與程式架構一致，macOS 的首次開啟權限已完成確認。
- 更新訂閱時能明確選擇透過代理或不透過代理，而不是依賴未知狀態。
- 複雜路由、DNS 與開機啟動先暫緩啟用，基礎連線穩定後再逐項新增。