diskfreespace() 函數返回值到底代表什麼？含義和單位全解析

gitbox 2025-09-19

： diskfreespace() （別名disk_free_space() ）返回的是當前PHP 進程在指定文件系統/分區上可用的字節數。返回值的單位是字節（bytes） ，注意它通常表示“對運行進程可用”的空間，而不是磁盤上的絕對總空閒字節（在Unix 上會受保留塊和權限影響；在32 位PHP 上還可能遭遇整數溢出問題）。

下面把重要細節拆開解釋並給出常見用法。

1. 基本用法與返回值類型

<span><span><span class="hljs-variable">$free</span></span><span> = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-string">'/'</span></span><span>); </span><span><span class="hljs-comment">// 或者 disk_free_space('/path/to/dir');</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"獲取失敗"</span></span><span>;
} </span><span><span class="hljs-keyword">else</span></span><span> {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"可用字節數： <span class="hljs-subst">$free</span></span></span><span>\n";
}
</span></span>

返回值單位：字節（bytes）。
可能的返回類型：在現代PHP（64 位）上通常是整數（int，64-bit），在某些環境或較舊PHP/32-bit 環境下可能是浮點數或出現溢出。函數在失敗時返回false並發出警告（warning）。
參數：傳入文件路徑或掛載點（例如C:\ 、 /var 、 /mnt/share ），不能直接傳入HTTP/FTP 等URL（需要本地或已掛載的路徑）。

2. “可用”並不總等於“絕對空閒”

diskfreespace()的結果通常等同於系統調用（如Unix 的statvfs或Windows 等價）的“available”字段，這表示對**當前用戶（或運行進程）**可用的字節數。因此：

在Unix/Linux 上，文件系統通常為root 保留一部分塊（比如5%），非root 用戶看不到這部分，返回值會不包含被保留的空間。
如果PHP 以非特權用戶運行，返回值反映的是該用戶可寫的空間，而不是超級用戶可使用的全部空閒空間。
對網絡掛載（NFS、SMB）或容器/虛擬機環境，返回數值也會受掛載選項和容器限制（quota、cgroups 等）影響。

因此——若要判斷磁盤是否“真正”空閒，需要結合權限、是否為root、以及文件系統的保留/配額設置來理解數值。

3. 與disk_total_space()的關係

disk_total_space()返回該分區的總字節數（總容量），而diskfreespace()返回可用字節數。兩者配合可以計算使用率：

 <span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>;
</span><span><span class="hljs-variable">$total</span></span><span> = </span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = </span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$free</span></span><span> !== </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
    </span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-title function_ invoke__">printf</span></span><span>(</span><span><span class="hljs-string">"總容量: %s, 可用: %s, 已用: %.2f%%\n"</span></span><span>, </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>), </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>), </span><span><span class="hljs-variable">$usedPercent</span></span><span>);
}
</span></span>

4. 數值單位和如何展示（常見錯誤點）

磁盤空間常用兩套單位定義：

二進制（常用於操作系統）： 1 KiB = 1024 bytes, 1 MiB = 1024 KiB = 10242 bytes, 1 GiB = 10243 bytes。
十進制（一些廠商或硬盤規格）： 1 KB = 1000 bytes, 1 MB = 10002 bytes。

PHP 返回字節數，若需“人類可讀”的展示，通常按二進制（1024）轉換更貼近操作系統工具（ df -h等通常顯示GiB）：

 <span><span><span class="hljs-function"><span class="hljs-keyword">function</span></span></span><span> </span><span><span class="hljs-title">formatBytes</span></span><span>(</span><span><span class="hljs-params"><span class="hljs-variable">$bytes</span></span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span> = </span><span><span class="hljs-number">2</span></span><span>) {
    </span><span><span class="hljs-keyword">if</span></span><span> (!</span><span><span class="hljs-title function_ invoke__">is_numeric</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>) || </span><span><span class="hljs-variable">$bytes</span></span><span> &lt; </span><span><span class="hljs-number">0</span></span><span>) </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-string">'0 B'</span></span><span>;
    </span><span><span class="hljs-variable">$units</span></span><span> = [</span><span><span class="hljs-string">'B'</span></span><span>,</span><span><span class="hljs-string">'KiB'</span></span><span>,</span><span><span class="hljs-string">'MiB'</span></span><span>,</span><span><span class="hljs-string">'GiB'</span></span><span>,</span><span><span class="hljs-string">'TiB'</span></span><span>,</span><span><span class="hljs-string">'PiB'</span></span><span>];
    </span><span><span class="hljs-variable">$i</span></span><span> = </span><span><span class="hljs-number">0</span></span><span>;
    </span><span><span class="hljs-keyword">while</span></span><span> (</span><span><span class="hljs-variable">$bytes</span></span><span> &gt;= </span><span><span class="hljs-number">1024</span></span><span> &amp;&amp; </span><span><span class="hljs-variable">$i</span></span><span> &lt; </span><span><span class="hljs-title function_ invoke__">count</span></span><span>(</span><span><span class="hljs-variable">$units</span></span><span>)-</span><span><span class="hljs-number">1</span></span><span>) {
        </span><span><span class="hljs-variable">$bytes</span></span><span> /= </span><span><span class="hljs-number">1024</span></span><span>;
        </span><span><span class="hljs-variable">$i</span></span><span>++;
    }
    </span><span><span class="hljs-keyword">return</span></span><span> </span><span><span class="hljs-title function_ invoke__">round</span></span><span>(</span><span><span class="hljs-variable">$bytes</span></span><span>, </span><span><span class="hljs-variable">$precision</span></span><span>) . </span><span><span class="hljs-string">' '</span></span><span> . </span><span><span class="hljs-variable">$units</span></span><span>[</span><span><span class="hljs-variable">$i</span></span><span>];
}
</span></span>

示例： 1073741824字節= 1073741824 / 1024^3 = 1 GiB （即1GiB）。

5. 常見陷阱與建議實踐

32 位溢出：在32 位PHP 上，較大的字節數可能超出int範圍，導致錯誤或浮點近似。盡量在64 位環境運行或用float /字符串處理大數。
檢查返回值：函數失敗時返回false ，應用=== false來判斷錯誤，而不是if (!$free) （因為0 字節也是假值）。
權限和保留塊：意識到返回的是“對當前進程可見/可用”的空間——如果你以web 服務器用戶運行，結果可能低於超級用戶可用量。
網絡文件系統（NFS/SMB） ：這些掛載可能返回不穩定或受掛載選項影響的值，應該結合具體掛載配置測試。
快速監控：若用於報警（如磁盤使用率> 90%），請使用disk_total_space()和diskfreespace()的組合，並保守設置閾值以避免被保留塊或配額誤導。

6. 完整示例：獲取可用空間並按百分比報警

<span><span><span class="hljs-meta">&lt;?php</span></span><span>
</span><span><span class="hljs-variable">$path</span></span><span> = </span><span><span class="hljs-string">'/'</span></span><span>; </span><span><span class="hljs-comment">// 要檢測的路徑</span></span><span>
</span><span><span class="hljs-variable">$total</span></span><span> = @</span><span><span class="hljs-title function_ invoke__">disk_total_space</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);
</span><span><span class="hljs-variable">$free</span></span><span>  = @</span><span><span class="hljs-title function_ invoke__">diskfreespace</span></span><span>(</span><span><span class="hljs-variable">$path</span></span><span>);

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$total</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span> || </span><span><span class="hljs-variable">$free</span></span><span> === </span><span><span class="hljs-literal">false</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"無法獲取磁盤信息（可能是路徑錯誤或權限不足）\n"</span></span><span>;
    </span><span><span class="hljs-keyword">exit</span></span><span>(</span><span><span class="hljs-number">1</span></span><span>);
}

</span><span><span class="hljs-variable">$used</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> - </span><span><span class="hljs-variable">$free</span></span><span>;
</span><span><span class="hljs-variable">$usedPercent</span></span><span> = </span><span><span class="hljs-variable">$total</span></span><span> &gt; </span><span><span class="hljs-number">0</span></span><span> ? (</span><span><span class="hljs-variable">$used</span></span><span> / </span><span><span class="hljs-variable">$total</span></span><span>) * </span><span><span class="hljs-number">100</span></span><span> : </span><span><span class="hljs-number">0</span></span><span>;

</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"路徑: <span class="hljs-subst">$path</span></span></span><span>\n";
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"總容量: "</span></span><span> . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$total</span></span><span>) . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"可用: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">formatBytes</span></span><span>(</span><span><span class="hljs-variable">$free</span></span><span>)  . </span><span><span class="hljs-string">"\n"</span></span><span>;
</span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"已用: "</span></span><span>     . </span><span><span class="hljs-title function_ invoke__">number_format</span></span><span>(</span><span><span class="hljs-variable">$usedPercent</span></span><span>, </span><span><span class="hljs-number">2</span></span><span>) . </span><span><span class="hljs-string">"%\n"</span></span><span>;

</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$usedPercent</span></span><span> &gt;= </span><span><span class="hljs-number">90</span></span><span>) {
    </span><span><span class="hljs-comment">// 舉例報警邏輯</span></span><span>
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">"警告：磁盤已使用超過 90%！\n"</span></span><span>;
}

</span><span><span class="hljs-comment">// formatBytes 函數同上</span></span><span>
</span></span>

7. 小結（要點回顧）

diskfreespace()返回字節數（bytes） ，代表當前PHP 進程在該掛載點上可用的空間，而非一定等於磁盤上所有用戶都能用的“絕對空閒量”。
結果受文件系統保留塊、權限、配額、網絡掛載和運行環境（容器/虛擬機）影響。
在展示時按1024 基數轉換為KiB/MiB/GiB 更貼近操作系統常見顯示方式。
永遠檢查=== false來處理錯誤，並在32 位環境小心大數溢出。