使用password_needs_rehash 總是返回true 是什麼原因？常見錯誤排查指南

gitbox 2025-08-17

在PHP中， password_needs_rehash函數是一個非常有用的工具，用於檢查給定的密碼哈希是否需要重新生成。通常，它在應用程序需要更新密碼哈希算法時非常有用，確保舊的哈希在使用新算法時仍然能夠正常工作。然而，在實際開發過程中，可能會遇到password_needs_rehash總是返回true的問題。本文將分析可能導致這一問題的原因，並給出一些常見的排查方法。

什麼是password_needs_rehash ？

password_needs_rehash函數接受兩個參數：

$hash ：一個已經使用password_hash生成的哈希字符串。
$options ：一個關聯數組，包含重新哈希所需要的算法設置。

這個函數的作用是檢查傳入的哈希值是否符合指定的選項。如果哈希算法、成本或其他選項不符合當前要求，函數將返回true ，提示開發者應該使用新的選項重新生成哈希。

可能導致問題的原因

1. 哈希值本身有問題

如果你傳入的哈希值是無效的，或者格式不符合password_hash函數的輸出格式， password_needs_rehash很可能總是返回true 。例如，如果哈希值被截斷或損壞，PHP無法正確解析它。

解決方案：

確認傳入的哈希值是否是有效的密碼哈希。你可以使用password_get_info函數來檢查哈希的詳細信息。如果它返回的algoName字段為空，那麼哈希值可能存在問題。

 <span><span><span class="hljs-variable">$hashInfo</span></span><span> = </span><span><span class="hljs-title function_ invoke__">password_get_info</span></span><span>(</span><span><span class="hljs-variable">$hash</span></span><span>);
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-variable">$hashInfo</span></span><span>[</span><span><span class="hljs-string">'algoName'</span></span><span>] === </span><span><span class="hljs-string">''</span></span><span>) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'哈希值無效'</span></span><span>;
}
</span></span>

2. 選項參數與哈希不匹配

password_needs_rehash函數的第二個參數$options是用來指定你想要的哈希算法設置（如算法、成本因子等）。如果你傳入的選項與原始哈希的設置不一致，函數會返回true ，因為它認為當前哈希不符合新的要求。

解決方案：

在調用password_needs_rehash時，確保$options參數與原始哈希時使用的設置一致。如果你希望檢查當前哈希是否符合默認的PASSWORD_DEFAULT算法和成本設置，可以這樣寫：

 <span><span><span class="hljs-variable">$options</span></span><span> = [</span><span><span class="hljs-string">'cost'</span></span><span> =&gt; </span><span><span class="hljs-number">10</span></span><span>];  </span><span><span class="hljs-comment">// 使用你當前應用中推薦的 cost 值</span></span><span>
</span><span><span class="hljs-keyword">if</span></span><span> (</span><span><span class="hljs-title function_ invoke__">password_needs_rehash</span></span><span>(</span><span><span class="hljs-variable">$hash</span></span><span>, PASSWORD_DEFAULT, </span><span><span class="hljs-variable">$options</span></span><span>)) {
    </span><span><span class="hljs-keyword">echo</span></span><span> </span><span><span class="hljs-string">'密碼哈希需要重新生成'</span></span><span>;
}
</span></span>

3. 傳入的哈希格式不支持

PHP的password_hash函數在哈希時支持不同的算法，如PASSWORD_BCRYPT 、 PASSWORD_ARGON2I和PASSWORD_ARGON2ID 。如果你在傳遞哈希值時，不小心使用了不支持的哈希格式， password_needs_rehash會始終返回true ，因為它無法解析或識別該哈希。

解決方案：

確保你所使用的哈希算法在當前PHP版本中受支持。如果你在開發環境中使用了過時的PHP版本，考慮升級PHP，或者使用與該版本兼容的哈希算法。

4. 代碼邏輯錯誤

有時候， password_needs_rehash總是返回true也可能是因為代碼邏輯中的錯誤。比如，可能在其他地方不小心修改了哈希值，或者調用時混淆了參數。

解決方案：

檢查你的代碼，確認在調用password_needs_rehash之前，哈希值和選項是否正確傳遞。比如，可以先打印出來哈希值和選項，確保它們符合預期。

 <span><span><span class="hljs-title function_ invoke__">var_dump</span></span><span>(</span><span><span class="hljs-variable">$hash</span></span><span>);
</span><span><span class="hljs-title function_ invoke__">var_dump</span></span><span>(</span><span><span class="hljs-variable">$options</span></span><span>);
</span></span>

5. PHP版本不兼容

不同版本的PHP可能在實現password_needs_rehash時會有細微的差異。在某些情況下，低版本的PHP可能存在bug，導致該函數在某些哈希情況下始終返回true 。

解決方案：

確認你使用的PHP版本已經修復了相關的bug。推薦使用最新的穩定版PHP，或者至少使用一個PHP 7.4或更高版本。

總結

password_needs_rehash函數的目的是幫助開發者在密碼哈希算法或設置發生變化時及時更新哈希，避免因使用過時的哈希值導致安全漏洞。然而，如果你遇到該函數總是返回true的問題，可以按照以下步驟進行排查：

確保哈希值有效且沒有損壞。
檢查傳遞的選項與哈希值是否匹配。
確保哈希值的格式與當前PHP版本兼容。
檢查代碼邏輯，確保參數傳遞正確。
確認你的PHP版本沒有已知的bug，或者升級到更高的版本。

通過這些排查方法，你應該能夠找到問題的根源並順利解決。