> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/zh-tw/contributing/reporting-issues.md).

# 回報問題

如何提交有用的錯誤回報與功能需求。

所有錯誤與功能請求都提交到 [GitHub Issues](https://github.com/jason5ng32/MyIP/issues)。此儲存庫提供兩個範本——錯誤報告與功能請求——選對範本可讓大家少跑一趟。

## 在你提交之前

{% hint style="info" %}
關於自架部署的多數回報，最後都證實是設定問題，而不是錯誤。請先檢查這些項目。
{% endhint %}

1. **搜尋既有議題**，包含開啟與已關閉的。你的問題可能已經有人回報、回答，或已在 `dev`.
2. **閱讀** [**常見問題**](/developer/zh-tw/reference/faq.md)**.** 其中涵蓋了常見的部署與設定問題。
3. **確認你的設定。** 需要 MaxMind——請參閱 [MaxMind 設定](/developer/zh-tw/getting-started/maxmind-setup.md)。有些功能依賴可選的 API 金鑰；請參閱 [選用 API 金鑰](/developer/zh-tw/configuration/optional-api-keys.md).
4. **試試最新版本。** 這個錯誤可能已經不存在了。

## 提交錯誤報告

請使用 **錯誤報告** 範本。它會自動標記為 `錯誤` 。此範本會要求以下內容。

### 環境

* 作業系統
* 瀏覽器（如果適用）
* Node 版本
* Vite 版本
* Vue 3 版本
* Docker 版本（如果適用）
* 部署方式——Vercel、Docker 或 Node
* 環境變數， **且移除所有密鑰**
* 任何其他相關軟體版本

{% hint style="danger" %}
絕對不要把 API 金鑰、權杖或 MaxMind 憑證貼到議題裡。請將它們遮蔽。如果你已經外洩了其中一個，請立刻更換。
{% endhint %}

### 描述與重現步驟

清楚描述這個錯誤，接著列出可重現它的編號步驟。重現步驟是回報中最有用的部分。

### 預期行為與實際行為

你預期會發生什麼，以及實際發生了什麼。若涉及任何視覺內容，螢幕截圖或短畫面錄製都會有幫助。

### 終端機與主控台日誌

範本特別指出這點很重要，而確實如此。只要適用，請同時提供以下內容：

* **終端機日誌** 來自後端——錯誤訊息與堆疊追蹤。
* **瀏覽器主控台日誌** 適用於前端中任何失敗的情況。

<details>

<summary>從後端取得更多細節</summary>

後端透過共用的 `pino` 記錄器輸出日誌。要在重現前擷取更多資訊，請提高層級：

```bash
LOG_LEVEL=debug pnpm dev
```

請參閱 [記錄](/developer/zh-tw/configuration/logging.md) 其他可調選項，包括 `LOG_FORMAT` 以及 `LOG_HTTP`.

</details>

### 可選補充

* **額外背景資訊** ——相關議題連結，以及其他任何相關資訊。
* **可能的解決方案** ——如果你已經有修正的想法，請描述它。如果你想親自撰寫，請說明並閱讀 [如何貢獻](/developer/zh-tw/contributing/how-to-contribute.md) 第一個。

## 提交功能請求

請使用 **功能請求** 範本。它會自動標記為 `增強功能` 會自動標記，並且會詢問四件事：

| 欄位          | 要寫什麼              |
| ----------- | ----------------- |
| 這是否與某個問題相關？ | 請具體描述這個請求背後的挫折感   |
| 描述你希望的解決方案  | 從使用者的角度來看，應該發生什麼事 |
| 描述你考慮過的替代方案 | 其他方法，以及它們為何不足     |
| 額外背景資訊      | 螢幕截圖、模型圖、先前實作的連結  |

請說明對使用者可見的好處，而不只是實作方式。從真實問題出發的請求，遠比從提議的 API 出發的請求更容易評估。

{% hint style="info" %}
打算自己打造這個功能嗎？仍然先開議題，並等待維護者確認方向後再寫程式。請參閱 [如何貢獻](/developer/zh-tw/contributing/how-to-contribute.md).
{% endhint %}

## 安全性問題不同

不要因為漏洞而開一般的錯誤報告。請改為遵循 [安全政策](/developer/zh-tw/contributing/security-policy.md) 。


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/zh-tw/contributing/reporting-issues.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.