diff --git a/messages/en/usage.json b/messages/en/usage.json
index 27b7ea6db..04932cca3 100644
--- a/messages/en/usage.json
+++ b/messages/en/usage.json
@@ -507,7 +507,8 @@
 
       "npm": {
         "title": "Option 3: npm",
-        "description": "Install globally via npm:"
+        "description": "Install globally via npm:",
+        "note": "Note: Avoid installing opencode-ai via npm mirror registries. Mirror registries may cause missing dependencies; use the official npm registry if you hit issues."
       },
 
       "bun": {
diff --git a/messages/ja/usage.json b/messages/ja/usage.json
index d2c8b9509..612d05235 100644
--- a/messages/ja/usage.json
+++ b/messages/ja/usage.json
@@ -507,7 +507,8 @@
 
       "npm": {
         "title": "方法3：npm",
-        "description": "npm でグローバルにインストール："
+        "description": "npm でグローバルにインストール：",
+        "note": "注: opencode-ai を npm のミラー（サードパーティ registry）経由でインストールするのは推奨しません。依存関係が欠ける場合があるため、問題が出たら公式 npm registry を使用してください。"
       },
 
       "bun": {
diff --git a/messages/ru/usage.json b/messages/ru/usage.json
index 44b1cc368..33bd591e3 100644
--- a/messages/ru/usage.json
+++ b/messages/ru/usage.json
@@ -507,7 +507,8 @@
 
       "npm": {
         "title": "Способ 3: npm",
-        "description": "Глобальная установка через npm:"
+        "description": "Глобальная установка через npm:",
+        "note": "Примечание: не рекомендуем устанавливать opencode-ai через npm-зеркала (сторонние registry). В зеркалах могут отсутствовать зависимости; при проблемах используйте официальный npm registry."
       },
 
       "bun": {
diff --git a/messages/zh-CN/usage.json b/messages/zh-CN/usage.json
index 0c5a0085a..0cf355274 100644
--- a/messages/zh-CN/usage.json
+++ b/messages/zh-CN/usage.json
@@ -503,7 +503,8 @@
 
       "npm": {
         "title": "方式三：npm",
-        "description": "也可以通过 npm 全局安装："
+        "description": "也可以通过 npm 全局安装：",
+        "note": "提示：不建议通过 npm 镜像源/第三方 registry 安装 opencode-ai，可能会导致依赖缺失；如遇问题请改用官方 npm registry。"
       },
 
       "bun": {
diff --git a/messages/zh-TW/usage.json b/messages/zh-TW/usage.json
index b875c0a56..62b7efb6f 100644
--- a/messages/zh-TW/usage.json
+++ b/messages/zh-TW/usage.json
@@ -503,7 +503,8 @@
 
       "npm": {
         "title": "方式三：npm",
-        "description": "也可以通過 npm 全局安裝："
+        "description": "也可以通過 npm 全局安裝：",
+        "note": "提示：不建議透過 npm 鏡像源/第三方 registry 安裝 opencode-ai，可能會導致依賴缺失；如遇問題請改用官方 npm registry。"
       },
 
       "bun": {
diff --git a/src/app/[locale]/usage-doc/page.tsx b/src/app/[locale]/usage-doc/page.tsx
index 4119d70fa..09173e34b 100644
--- a/src/app/[locale]/usage-doc/page.tsx
+++ b/src/app/[locale]/usage-doc/page.tsx
@@ -996,6 +996,7 @@ gemini`}
             <CodeBlock language="powershell" code={`npm install -g opencode-ai`} />
           </div>
 
+          <p className="text-sm text-muted-foreground">{t("opencode.installation.npm.note")}</p>
           <p className="text-sm text-muted-foreground">{t("opencode.installation.windows.note")}</p>
         </div>
       );
@@ -1045,6 +1046,7 @@ gemini`}
           <CodeBlock language="bash" code={`npm install -g opencode-ai`} />
         </div>
 
+        <p className="text-sm text-muted-foreground">{t("opencode.installation.npm.note")}</p>
         <div className="space-y-3">
           <h5 className="font-semibold text-foreground">{t("opencode.installation.bun.title")}</h5>
           <p>{t("opencode.installation.bun.description")}</p>
diff --git a/tests/unit/usage-doc/opencode-usage-doc.test.tsx b/tests/unit/usage-doc/opencode-usage-doc.test.tsx
index f0adc8baa..3016735c7 100644
--- a/tests/unit/usage-doc/opencode-usage-doc.test.tsx
+++ b/tests/unit/usage-doc/opencode-usage-doc.test.tsx
@@ -92,6 +92,7 @@ describe("UsageDoc - OpenCode 配置教程", () => {
 
     expect(text).toContain("curl -fsSL https://opencode.ai/install | bash");
     expect(text).toContain("npm install -g opencode-ai");
+    expect(text).toContain("npm mirror registries");
     expect(text).toContain("bun add -g opencode-ai");
     expect(text).toContain("brew install anomalyco/tap/opencode");
     expect(text).toContain("paru -S opencode-bin");
@@ -112,6 +113,7 @@ describe("UsageDoc - OpenCode 配置教程", () => {
       expect(usageMessages).toHaveProperty("opencode.installation.title");
       expect(usageMessages).toHaveProperty("opencode.installation.script.title");
       expect(usageMessages).toHaveProperty("opencode.installation.npm.title");
+      expect(usageMessages).toHaveProperty("opencode.installation.npm.note");
       expect(usageMessages).toHaveProperty("opencode.installation.bun.title");
       expect(usageMessages).toHaveProperty("opencode.installation.macos.homebrew.title");
       expect(usageMessages).toHaveProperty("opencode.installation.linux.homebrew.title");
diff --git a/tests/unit/usage-doc/usage-doc-page.test.tsx b/tests/unit/usage-doc/usage-doc-page.test.tsx
index 1ddebb80f..055b578ed 100644
--- a/tests/unit/usage-doc/usage-doc-page.test.tsx
+++ b/tests/unit/usage-doc/usage-doc-page.test.tsx
@@ -62,7 +62,10 @@ describe("UsageDocPage - 目录/快速链接交互", () => {
       writable: true,
     });
 
-    document.cookie = "auth-token=test-token";
+    Object.defineProperty(document, "cookie", {
+      configurable: true,
+      get: () => "auth-token=test-token",
+    });
 
     const { unmount } = await renderWithIntl("en", <UsageDocPage />);
 
@@ -73,6 +76,8 @@ describe("UsageDocPage - 目录/快速链接交互", () => {
     expect(dashboardLink).not.toBeNull();
 
     await unmount();
+
+    Reflect.deleteProperty(document, "cookie");
   });
 
   test("目录项点击后应触发平滑滚动", async () => {