# Claude Code 看不到專案檔案：原因與處理方式（2026）

> Claude Code 找不到專案檔案的原因：啟動時所在的資料夾不對、檔案位於子資料夾，或檔案列在 .gitignore 中。本文說明如何使用 add-dir、cd 和設定授予存取權。

Source: https://ailoot.ai/blog/zh-hant-tw/claude-code-cant-see-project-files/
Canonical: https://ailoot.ai/blog/zh-hant-tw/claude-code-cant-see-project-files/
Language: zh-Hant-TW
Publisher: Ailoot (https://ailoot.ai/)
Translation: guide-199
Revision: sha256-667ba19fe94f46bbe2f40d358b0f30cea9f8793045b72f3afdbe0ba84f1310d7


這種情況很常見：你請 Claude Code 修正某個檔案，它卻回答說沒有這個檔案。或者，它悄悄修改了完全不是你要的內容。你打開資料夾一看，檔案明明就在該在的位置。但 Claude 似乎沒有注意到它。

幾乎總是只有一個原因，而且沒有任何東西壞掉。Claude 看不到整台電腦上的檔案，只能存取你啟動它時所在的資料夾。從同層其他資料夾或專案根目錄下層啟動，可能讓必要檔案位於工作樹外；從家目錄等上層啟動則範圍更廣，不會讓子專案因此無法存取。我會逐步說明為什麼會這樣，以及如何讓 Claude 存取需要的檔案。文中的命令和設定直接引用 Claude Code 官方文件；我在 2026 年 9 月上旬查閱過這些文件。

如需設定工具的補充資料，請參閱 [Ailoot 文件](https://ailoot.ai/docs/)。

<div class="aside" data-semantic="ailoot-cta" role="note" aria-label="Ailoot Guides">

[Ailoot 指南](https://ailoot.ai/docs/)

</div>

## 為什麼 Claude Code 看不到某些專案檔案？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

Claude Code 讀取檔案的範圍不是整個磁碟，而是你啟動它時所在的資料夾。這個資料夾稱為工作目錄。Claude 可以查看並讀取其中及其子資料夾內的所有內容，不必先詢問。工作目錄以外的內容——例如相鄰資料夾、上一層資料夾或另一個磁碟上的內容——都無法存取，除非你自行授予存取權。因此，檔案「看不到」最常見的原因很簡單：你從不同的資料夾啟動了 Claude。先確認你究竟是從哪裡開啟它的。

</div>

Claude Code 預設只會使用一個資料夾：你輸入 `claude` 命令並啟動工作階段的那個資料夾。官方文件對此有明確說明。

<figure>
<blockquote>
<p>Claude 預設可以存取你啟動它時所在資料夾中的檔案。</p>
</blockquote>
<figcaption>— Claude Code Docs，設定權限，官方文件</figcaption>
</figure>

這個資料夾就是它的工作目錄。在這個資料夾內，Claude 不必額外詢問就能讀取任何檔案：編輯提示、搜尋程式碼、讀取特定檔案，都可以立即進行。但預設情況下，這個資料夾以外的所有內容都無法存取。Claude 不會查看相鄰資料夾、上一層資料夾或另一個磁碟，除非你允許它這麼做。

工作目錄不符確實可能有影響。例如專案在 `/Users/you/my-shop`，卻從同層 `/Users/you/other-project` 啟動，my-shop 的 `index.html` 位於該工作樹外。若從 `/Users/you` 啟動，my-shop 則是子目錄，不會只因起點是家目錄就無法存取，但範圍比預期大。可存取也不代表每個檔案都已讀取。

接下來，我會說明如何檢查並解決這個問題：先確認 Claude 是從哪個資料夾啟動，再透過不同方式授予它存取所需檔案的權限，從一次性的指示到永久設定都有。

## 如何確認 Claude Code 是從哪個資料夾啟動的？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

你可以問 Claude 目前在哪個資料夾，或請它使用 `pwd` 命令顯示目前目錄；這只會進行檢查，不會變更任何內容。將顯示的路徑與專案實際位置比較。如果路徑不同，原因就在這裡：Claude 是從錯誤的資料夾啟動的。更可靠的解決方式是關閉工作階段，直接從專案資料夾重新啟動 Claude：在終端機中切換到該資料夾，然後在那裡輸入 `claude`。

</div>

在修正任何設定之前，先確認問題確實出在資料夾。這很容易檢查。在聊天中請 Claude 顯示目前所在的目錄，它會執行 `pwd`。這個命令很安全，只會顯示路徑，不會改動任何內容。

```bash
pwd
```

回覆會顯示實際工作目錄。請與完整專案路徑比較：`/Users/you/other-project` 與 `/Users/you/my-shop` 同層，`/Users/you` 則是上層。同層情況讓 my-shop 位於工作樹外，上層包含它，但沒有以該專案為根目錄。

最直接的解決方式是從專案資料夾直接啟動 Claude。關閉目前的工作階段，在終端機中切換到正確的資料夾，再從該處啟動 Claude：

```bash
# 將示意路徑換成實際專案根目錄。
cd /Users/you/my-shop
claude
```

現在 `my-shop` 就是工作資料夾，所有專案檔案都會進入視野。在 VS Code 之類的編輯器中也遵循相同原則：開啟包含專案的資料夾。不要開啟上一層資料夾，也不要開啟整個磁碟。你開啟的資料夾，決定了 Claude 認定的工作目錄。

如果重新啟動不方便——例如你已經在這個工作階段中提供 Claude 背景資訊，不想失去它——也可以在執行期間新增或切換資料夾。接下來兩個章節會說明這些方式。

## 如何讓 Claude Code 查看相鄰資料夾中的檔案？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

不必重新啟動工作階段，就能在聊天中直接使用 `/add-dir` 命令加入所需資料夾：輸入 `/add-dir` 和資料夾路徑，Claude 就能像存取主要資料夾中的檔案一樣存取其中的檔案。若要在 Claude 啟動時就開放存取，請在 `claude` 命令中加入帶有路徑的 `--add-dir` 旗標。如果你希望每次都自動開啟某個資料夾，請在設定的 `additionalDirectories` 鍵中加入該資料夾。這三種方式都能讓 Claude 讀取新增資料夾中的檔案，而不必逐一確認。

</div>

有時候，專案不只放在一個資料夾裡。程式碼放在一處，圖片或文字放在相鄰資料夾，共用元件則放在附近的另一處。每次都在不同資料夾重新啟動 Claude 很不方便。比較好的做法是在保留主要資料夾為工作目錄的同時，授予 Claude 存取所需資料夾的權限。

最簡單的方法是在目前的工作階段中直接輸入以下命令：

```
/add-dir ../assets
```

輸入 `/add-dir` 和資料夾路徑後，Claude 就能立即存取其中的檔案，權限與主要資料夾中的檔案相同。它不會再次詢問許可，因為新增的資料夾遵循與工作目錄相同的規則。

<figure>
<blockquote>
<p>額外目錄中的檔案遵循與主要工作目錄相同的存取規則：讀取時不會詢問。</p>
</blockquote>
<figcaption>— Claude Code Docs，設定權限，官方文件</figcaption>
</figure>

如果你事先就知道會使用多個資料夾，可以在 Claude 啟動時就開放存取。使用相同路徑，但加上旗標：

```bash
claude --add-dir ../assets
```

如果你在同一個專案中總是需要使用相鄰資料夾，就不必每次手動加入。`settings.json` 設定檔中有一個 `additionalDirectories` 鍵。將路徑列在其中，Claude 每次啟動時就會自動開啟這些資料夾：

```json
{
  "permissions": {
    "additionalDirectories": ["../assets", "../shared"]
  }
}
```

Windows 使用者要注意一點：不能使用 `\\server\shared` 這類路徑加入網路資料夾，Claude 不接受這種路徑。請將網路資料夾掛載為使用磁碟機代號的獨立磁碟，再透過 `--add-dir` 傳入該磁碟機代號。一般的本機資料夾沒有這個問題。

如果只加入相鄰資料夾還不夠，而你需要完全切換到另一個資料夾，則有另一個專用命令，以下會介紹。

## 如何在工作階段中將 Claude Code 切換到另一個資料夾？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

`/cd` 命令可以在不關閉工作階段的情況下變更主要工作資料夾：輸入 `/cd` 和路徑，Claude 就會在保留對話記錄的情況下移到該處。移動時，它會載入新資料夾中的 `CLAUDE.md` 指示檔；如果你以前沒有在那裡工作過，還會請你確認是否信任該資料夾。`/add-dir` 是在主要資料夾旁新增一個資料夾，`/cd` 則是將整個工作目錄移到新位置。此命令從版本 2.1.169 起提供。

</div>

有時候，加入相鄰資料夾還不夠，你需要切換到另一個專案，但不想失去已建立的對話脈絡。這時請使用 `/cd` 命令：

```
/cd ../another-project
```

之後，Claude 會將新資料夾視為工作目錄。你會保留完整的對話記錄，但 Claude 查找檔案的參照位置會改為新位置。如果新資料夾中有 `CLAUDE.md` 指示檔，Claude 也會載入它，也就是會遵循新專案的規則。

有一點關於信任的事項要留意：如果你以前沒有在這個資料夾中工作過，移動到該處時 Claude 會詢問你是否信任它。這是一項安全防護：陌生資料夾中的指示檔可能包含任何內容，因此 Claude 會先確認這是你的專案。確認後就可以繼續。

這兩個命令的差異很簡單。`/add-dir` 保留主要資料夾作為工作目錄，並在旁邊額外開啟一個資料夾，適合專案各部分散落在不同位置的情況。`/cd` 則將整個工作目錄移到新位置，適合切換到另一個專案。`/cd` 命令是在版本 2.1.169 中加入的。如果找不到這個命令，請更新 Claude Code。我另有一篇指南介紹[如何更新 Claude Code](https://ailoot.ai/blog/zh-hant-tw/update-claude-code/)。

Claude Code 能看到檔案只是基礎。穩定的結果不會只靠檔案存取權而來，還取決於檔案的內容，以及你如何為專案建立脈絡。

<div class="aside" data-semantic="ailoot-cta" role="note" aria-label="Ailoot Guides">

[Ailoot 指南](https://ailoot.ai/docs/)

</div>

## 為什麼 Claude Code 看不到子資料夾中的檔案？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

子資料夾和相鄰資料夾的運作方式不同：Claude 可以存取子資料夾，但其中的內容不會立刻進入它的脈絡。Claude 會在需要時查看子資料夾，並載入指示檔和其中內容，不會在啟動時就全部載入。因此，深層子資料夾中的檔案可能會「看不見」，直到你直接提供它的路徑。解決方法很簡單：提供檔案的完整路徑，或先請 Claude 讀取檔案，它就會出現在脈絡中。

</div>

要注意不要混淆兩種不同情況。相鄰資料夾（專案之外的資料夾）在你加入之前完全無法存取。專案內的子資料夾則不同：Claude 可以存取，但一開始不會將其中內容放在脈絡裡。

運作方式如下：Claude 啟動時會載入專案較上層的內容。它會在需要讀取子資料夾檔案並查看該處時，才按需載入那些檔案。官方文件描述了指示檔的這種行為，而一般脈絡也遵循相同邏輯。

<figure>
<blockquote>
<p>Claude 會探索工作目錄的子資料夾中的檔案。它不會在啟動時載入這些檔案，而是在讀取子資料夾中的檔案時才將它們載入。</p>
</blockquote>
<figcaption>— Claude Code Docs，管理 Claude 的記憶，官方文件</figcaption>
</figure>

簡單來說，深層子資料夾中的檔案並沒有消失，而且完全可以存取。Claude 只是還沒去查看，所以尚未記住它。這就解釋了為什麼即使檔案明明存在且可以存取，Claude 還是會讓人覺得「看不到」它。

一行指示就能解決。直接提供檔案路徑，例如 `src/components/header.jsx`，或直接請 Claude 先讀取檔案。它一查看，檔案就會進入脈絡，你便能照常處理。不需要變更任何設定。

## 檔案為什麼會從 @ 選單消失？這和 .gitignore 有什麼關係？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

輸入 `@` 符號時，Claude Code 會顯示可供選擇的檔案清單。預設情況下，這個清單會隱藏 `.gitignore` 中列出的內容，例如服務資料夾、環境檔案和建置輸出。因此，檔案可能就在正確的位置，卻沒有出現在 `@` 選單中。`respectGitignore` 設定會控制這項行為：預設為開啟，會隱藏這些檔案。將它設為 `false`，選單就會一併顯示 `.gitignore` 中列出的檔案。你也可以隨時手動輸入這類檔案的路徑。

</div>

另一個常讓人以為 Claude「弄丟」檔案的原因，是檔案選擇器。輸入 `@` 後會出現清單，方便你選取檔案，不必輸入完整路徑。但清單不會顯示所有內容。

預設情況下，`@` 選單會隱藏 `.gitignore` 中列出的檔案。這個檔案用來指定哪些內容不應加入共用儲存庫，例如服務資料夾、含有密碼和環境設定的檔案，以及已完成的建置輸出。這樣設計有其道理：通常你不需要手動處理這些檔案，因此將它們列出只會讓清單更雜亂。但有時你確實需要其中某個檔案，它卻沒有出現在選單裡。

這項行為由 `respectGitignore` 設定控制。它預設為開啟，因此 `.gitignore` 中的檔案不會出現在選單中。如果想查看這些檔案，請將它切換為 `false`：

```json
{
  "respectGitignore": false
}
```

你也可以不編輯檔案，直接在 Claude Code 中使用 `/config` 命令完成相同設定。切換選項名為「Respect .gitignore in file picker」。取消勾選後，隱藏的檔案就會重新出現在選單中。

有一點要特別注意：`respectGitignore` 只影響 `@` 選單，與檔案存取權無關。即使檔案在清單中被隱藏，你仍然可以手動輸入它的路徑，Claude 也會讀取它。選單只是便利功能，不會設定存取範圍。

## Claude Code 無法讀取特定檔案時該怎麼辦？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

有時資料夾正確，但 Claude 仍拒絕讀取某個特定檔案。通常是設定中的限制所造成。`settings.json` 檔案可能包含禁止讀取特定檔案的 `deny` 規則，最常見的是含有金鑰和密碼的 `.env` 檔案。另外也有一項設定，可全面禁止讀取工作資料夾之外的內容。請檢查 `settings.json` 中這兩處設定。也請記得，限制讀取 `.env` 是預設的安全防護；除非有充分理由，否則不應移除。

</div>

如果資料夾確定正確、存取權也已開放，但 Claude 仍不讀取某個特定檔案，最可能是該檔案受到限制。限制位於 `settings.json` 設定檔中，分為兩種。

第一種是針對特定檔案的限制。在設定中，這類限制稱為 `deny` 規則，最常套用在 `.env` 檔案上，因為金鑰和密碼通常存放在其中：

```json
{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}
```

這類規則會禁止 Claude 讀取指定的檔案，而且這是刻意設計的。金鑰和密碼不應出現在與模型的對話中，所以 `.env` 預設會受到保護。如果你發現 Claude 不會讀取 `.env` 或其他含有祕密資訊的類似檔案，這是預期行為；除非有充分理由，否則不應移除此限制。

第二種是對工作資料夾以外所有內容的全面限制。這項限制由 `blockReadsOutsideWorkingDirectories` 設定控制。啟用後，即使你直接嘗試開啟，Claude 也會拒絕讀取工作目錄之外的任何檔案。如果它設為 `true`，而你需要使用外部檔案，可以透過 `/add-dir` 加入該檔案所在的資料夾，或關閉這項限制：

```json
{
  "permissions": {
    "blockReadsOutsideWorkingDirectories": false
  }
}
```

這項設定是在版本 2.1.257 中加入的。如果你已嘗試其他方法，但檔案仍然無法存取，請一併檢查 `deny` 和 `blockReadsOutsideWorkingDirectories`。

## Claude Code 看不到檔案時，應該從哪裡開始？

<div class="aside" data-semantic="key-takeaway" role="note" aria-label="Key takeaway">

重點摘要

先檢查資料夾：請 Claude 使用 `pwd` 顯示目前目錄，並與專案位置比較。如果兩者不一致，請從專案資料夾重新啟動 Claude，或使用 `/cd` 移到該處。需要相鄰資料夾中的檔案？用 `/add-dir` 開啟它。看不到子資料夾中的檔案？直接提供路徑。檔案沒有出現在 `@` 選單中？問題與 `.gitignore` 有關，請切換 `respectGitignore`。只有一個檔案被鎖定？檢查 `settings.json` 中的 `deny` 限制。

</div>

以下是可以按順序執行的簡短步驟。

1.  檢查工作資料夾：請 Claude 使用 `pwd` 顯示目前目錄，並與專案位置比較。
2.  如果資料夾不同，請從正確的資料夾重新啟動 Claude（執行 `cd project`，再執行 `claude`），或使用 `/cd` 命令移到該處。
3.  需要相鄰資料夾中的檔案？使用 `/add-dir`，或在啟動 Claude 時使用 `--add-dir` 旗標加入該資料夾。
4.  子資料夾中的檔案尚未進入脈絡？直接提供路徑，或請 Claude 讀取該檔案。
5.  檔案沒有出現在 `@` 選單中？這和 `.gitignore` 有關。將 `respectGitignore` 設為 `false`，或在 `/config` 中取消勾選。
6.  某個特定檔案遭到鎖定？檢查 `settings.json` 中的 `deny` 和 `blockReadsOutsideWorkingDirectories` 規則。

十個案例中有九個，只要執行第一步就能解決：Claude 是從錯誤的資料夾啟動的。檔案存取是基礎，但不會替你建構專案。我已在[Claude Code 中的 Second Brain](https://ailoot.ai/blog/zh-hant-tw/claude-code-second-brain/)指南中，詳細說明如何為 Claude 建立脈絡，讓它記住整個專案，不致失去思路。

<div class="section" role="doc-bibliography" aria-label="Sources">

### 來源

- [Claude Code - 設定權限，官方文件](https://docs.claude.com/en/docs/claude-code/permissions) - 預設工作目錄、--add-dir 和 /add-dir、/cd、additionalDirectories、不經提示即可存取、網路路徑
- [Claude Code - 管理 Claude 的記憶，官方文件](https://docs.claude.com/en/docs/claude-code/memory) - 按需載入子資料夾檔案、CLAUDE.md、匯入
- [Claude Code - 設定參考，官方文件](https://docs.claude.com/en/docs/claude-code/settings-reference) - respectGitignore 與 @ 選單、blockReadsOutsideWorkingDirectories 與版本 2.1.257
- [Claude Code - 設定，官方文件](https://docs.claude.com/en/docs/claude-code/settings) - deny 規則與禁止讀取 .env

</div>

如需更多工具使用資料，請參閱 [Ailoot 文件](https://ailoot.ai/docs/)。



<div class="aside" data-semantic="ailoot-cta" role="note" aria-label="Ailoot Guides">

[Ailoot 指南](https://ailoot.ai/docs/)

</div>

<div class="aside" data-semantic="ailoot-cta" role="note" aria-label="Go to Ailoot">

[前往 Ailoot](https://ailoot.ai/)

</div>

## 常見問題：Claude Code 看不到專案檔案：原因與處理方式（2026）

### 從家目錄啟動，與從旁邊另一個專案啟動有何不同？

家目錄下的專案是子目錄，從家目錄啟動不會因此把它排除，只會範圍過大。工作目錄旁的同層專案則在該樹之外；診斷前先比較完整路徑。

### 能存取子資料夾，就代表檔案已在上下文嗎？

不是。請提供路徑並要求讀取，若拒絕再查適用權限。未出現在選取選單，與實際讀取遭拒，是不同問題。


## Ailoot · 公司及其專案組合

Ailoot以累積的營運經驗、廣大的客戶群、穩定的服務及持續的KPI管理為基礎。

公司及其專案組合：數百萬客戶，每月銷售額達數十億。

Ailoot將這些營運經驗用於API存取，讓客戶的產品、代理、應用程式及自動化流程使用AI功能。