一、Web 環境 (ASP.NET / ASP.NET Core)
| 需求 | API / 語法 | 回傳範例 | 備註 |
| 應用程式根目錄 (WebRoot) | HttpContext.Current.Server.MapPath("~") / IWebHostEnvironment.WebRootPath | D:\WebApp\ | ASP.NET Core 注入 IWebHostEnvironment |
| 內容根目錄 (ContentRoot) | HttpRuntime.AppDomainAppPath / IWebHostEnvironment.ContentRootPath | D:\WebApp\ | 含 App_Data、Views 等非公開資源 |
| 當前請求虛擬路徑 | Request.Path / Request.RawUrl | /Home/Index | |
| 當前請求實體路徑 | Request.MapPath(Request.Path) / Server.MapPath(Request.Path) | D:\WebApp\Home\Index.cshtml | |
| 應用程式相對路徑 (~) | ~/Scripts/app.js (僅支援 runat=server 控制項、MVC/Razor 輔助方法) | 自動解析為 /App/Scripts/app.js | 一般字串不會自動解析 |
| 相對路徑 . / .. | ./file.txt、../folder/file.txt | 相對當前執行檔/請求路徑 | 建議避免,易因工作目錄變更失效 |
二、非 Web 環境 (Console / WinForms / WPF / Service)
| 需求 | API | 回傳範例 | 備註 |
| 執行檔所在目錄 | AppDomain.CurrentDomain.BaseDirectory | D:\App\bin\Debug\ | 最穩定,含結尾斜線 |
| 執行檔完整路徑 | Process.GetCurrentProcess().MainModule.FileName | D:\App\bin\Debug\App.exe | 需 using System.Diagnostics; |
| 目前工作目錄 | Environment.CurrentDirectory / Directory.GetCurrentDirectory() | D:\App\ | 可被 chdir 改變,不可靠 |
| 專案輸出目錄下資料檔 | Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Data", "config.json") | | 建議用 Copy to Output Directory 複製資料檔 |
三、通用路徑操作最佳實務 (System.IO.Path)
// 路徑合併 (自動處理分隔符)
string full = Path.Combine(baseDir, "sub", "file.txt");
// 取得目錄、檔名、副檔名
string dir = Path.GetDirectoryName(full);
string name = Path.GetFileName(full);
string ext = Path.GetExtension(full);
string nameNoExt = Path.GetFileNameWithoutExtension(full);
// 取得絕對路徑 (解析相對路徑)
string abs = Path.GetFullPath(relativePath);
// 取得暫存檔路徑
string tmpFile = Path.GetTempFileName();
string tmpDir = Path.GetTempPath();
// 路徑標準化 (解析 ..、.、符號連結)
string canonical = Path.GetFullPath(new Uri(path).LocalPath); // .NET Core 2.1+
四、Server.MapPath 經典用法對照 (ASP.NET 傳統)
// 在 Content/UserInfoManager.aspx.cs 中
string tempPath = Server.MapPath("UploadResourceImage");
// 回傳: D:\WebApp\Content\UploadResourceImage
// 常見變體
Server.MapPath("~/UploadResourceImage"); // 從根目錄
Server.MapPath("../UploadResourceImage"); // 相對當前目錄
Server.MapPath(Request.RequestURI); // 當前請求對應實體路徑
五、跨平台路徑陷阱與解決
- 分隔符:Windows
\、Linux/Mac /。永遠使用 Path.Combine、Path.DirectorySeparatorChar。
- 大小寫敏感:Linux 區分大小寫,部署前驗證路徑大小寫一致性。
- 路徑長度:Windows 260 字元限制 (可透過
\\?\ 前綴或啟用 LongPaths 注冊表突破)。
- 權限:非 Web 環境寫入
Program Files 需管理員權限,建議寫入 AppData 或 CommonApplicationData。
六、現代化建議 (.NET Core / .NET 5+)
- 注入
IWebHostEnvironment (Web) 或 IHostEnvironment (Generic Host) 取得 ContentRootPath/WebRootPath。
- 使用
IFileProvider 抽象檔案系統,支援實體、嵌入資源、記憶體、監看變更。
- 配置檔採用
appsettings.json + IConfiguration,避免硬編碼路徑。
結語
路徑處理看似瑣碎,實則關係部署可攜性與安全性。核心原則:Web 用 IWebHostEnvironment、非 Web 用 AppDomain.BaseDirectory、統一用 Path.Combine、拒絕硬編碼相對路徑、資料檔外部化配置。