????????在使用 VuePress 搭建個人博客并部署到 GitHub Pages 的過程中，我遇到了一個頗為棘手的問題：本地打包一切正常，但在 GitHub Actions 自動執行打包流程時，卻提示找不到 README.md 文件，導致整個流程失敗。經過一番深入排查和嘗試，終于成功解決了這個問題，在此將整個過程記錄下來，希望能幫助到遇到類似情況的開發者。

一、問題出現

????????我的 VuePress 項目在本地運行 npm run docs:build 時，一切都按預期進行，順利生成了靜態文件，并且我自定義的將根目錄下的 README.md 文件復制到構建輸出目錄的操作也毫無問題。然而，當我將代碼推送到 GitHub 倉庫后，GitHub Actions 工作流啟動，卻在執行到復制 README.md 文件這一步時出錯，日志中清晰地顯示：

????????這讓我十分困惑，因為 README.mdR 文件確實就存在于項目的根目錄下，本地能正常識別，為何在 GitHub Actions 中就找不到了呢？

二、排查過程

（一）初步懷疑文件未正確檢出

????????首先，我懷疑是 GitHub Actions 在檢出代碼時出現了問題，導致 README.md 文件沒有被正確下載到運行環境中。我檢查了工作流中的 actions/checkout 步驟，發現并沒有明顯的配置錯誤。不過，為了確保完整檢出倉庫歷史，我在該步驟中添加了 fetch-depth: 0 參數，重新推送代碼觸發工作流，結果問題依舊存在。

（二）考慮路徑差異

????????接著，我意識到本地和 GitHub Actions 的運行環境可能存在路徑差異。在本地開發時，我習慣了特定的文件路徑結構，但 GitHub Actions 運行在 Ubuntu 環境下，其工作目錄可能與我預期的不同。為了驗證這一點，我在復制文件的 copy-readme.js 腳本中添加了打印當前工作目錄的語句：

console.log('當前工作目錄:', __dirname);

????????重新運行工作流后，從日志中看到工作目錄為 /home/runner/work/vivien-blog-code/vivien-blog-code，這與預期相符，說明路徑結構本身沒有問題。

（三）關注分支情況

????????我又想到可能是分支的問題。也許我在本地測試時使用的分支和 GitHub Actions 觸發工作流的分支不一致，而 README.md 文件只存在于我本地測試的分支中。仔細檢查了工作流配置中的 on.push.branches 字段，發現配置的正是我本地使用的 main 分支，排除了分支不一致的可能性。

（四）檢查緩存及權限

????????考慮到緩存可能帶來的影響，我在工作流中添加了清除 node_modules 緩存的步驟，重新運行后問題仍然沒有解決。同時，我也檢查了文件權限，在復制文件前添加了設置文件權限的命令 chmod -R 755.，但依舊未能成功。

（五）發現文件名大小寫問題

????????在幾乎排查了所有可能的常規問題后，我突然想到在 Linux 環境下文件名是大小寫敏感的。我仔細檢查了本地的?README.md 文件，發現文件名中的 .md 部分實際上是大寫的，即 README.MD。而我的 copy-readme.js 腳本和 package.json 中的構建腳本都是按照 README.md
來查找文件的，這很可能就是問題的根源！

三、問題解決

（一）修改文件后綴

????????我立即將 README.MD 文件名修改為?README.md?

? ? ? ? 但這里有個問題，git 是不區分大小寫的，所以我改了后綴后推送，發現遠程倉庫中的文件依然是?README.MD。

? ? ? ? 于是，我先把?README.MD 文件給刪了，推送一次，再重新創建一個?README.md，推送一次，完美解決

? ? ? ? 此時遠程倉庫中的 README.md 文件也正確了。?

（二）重新推送驗證

????????修改完成后，我將代碼重新推送到 GitHub 倉庫。這次，GitHub Actions 工作流順利運行，成功完成了打包過程，并且 README.md 文件也被正確地復制到了構建輸出目錄中。困擾我許久的問題終于得到了解決。

四、總結與啟示

????????這次解決問題的經歷讓我深刻認識到在跨環境開發和部署過程中，一些看似微不足道的細節可能會引發嚴重的問題。文件名大小寫敏感就是一個很容易被忽視的點，尤其是在本地開發環境（如 Windows）對文件名大小寫不敏感的情況下。

????????同時，詳細的日志記錄和逐步排查問題的方法也非常重要，它們能幫助我們快速定位到問題的關鍵所在，提高解決問題的效率。