fix: 清理 usage-doc / big-screen i18n 硬编码 + 修复 Next.js params Promise 报错 by YangQing-Lin · Pull Request #595 · ding113/claude-code-hub

YangQing-Lin · 2026-01-12T13:46:47Z

Summary

Fix Edge Runtime build warnings caused by process.once Node.js API usage in AsyncTaskManager import chain. The fix skips initialization in Edge/CI/build environments and uses dynamic imports to prevent static bundling.

Note: This PR appears to be a duplicate of #589 which was already merged. Consider closing this PR.

Related Issues:

Follow-up to fix: 修复 middleware 和 API routes 的 Edge Runtime 兼容性问题 #8 - Previous Edge Runtime compatibility fix for middleware and API routes

Problem

During next build (Turbopack/Next), Edge Runtime warnings appear because process.once is a Node.js API not supported in Edge Runtime.

The import trace shows:

src/lib/async-task-manager.ts
src/lib/price-sync/cloud-price-updater.ts
src/instrumentation.ts

Root cause: AsyncTaskManager registers process.once(...) exit signal hooks during module initialization, which gets pulled into the Edge Instrumentation bundle via the dependency chain.

Solution

Two-layer defense to prevent Edge bundle from seeing process.once:

1) AsyncTaskManager: Lazy initialization with environment guards

Convert from constructor-based to lazy initialization pattern (initializeIfNeeded())
Skip initialization when NEXT_RUNTIME === "edge", CI === "true", or NEXT_PHASE === "phase-production-build"
Defer Node.js API calls (process.once, setInterval) until first register() call

2) cloud-price-updater: Dynamic import + Edge runtime no-op

Remove static import of AsyncTaskManager to prevent bundler from pulling it into Edge bundle
Use dynamic import() inside async function, only in Node.js runtime
Add early return for NEXT_RUNTIME === "edge"
Add global scheduling flag to prevent concurrent loading races

Changes

Core Changes

src/lib/async-task-manager.ts - Lazy initialization with environment guards (+20/-4)
src/lib/price-sync/cloud-price-updater.ts - Dynamic import with Edge runtime no-op (+57/-32)

Supporting Changes

tests/unit/lib/async-task-manager-edge-runtime.test.ts - Edge runtime test coverage (+308 lines)
tests/unit/price-sync/cloud-price-updater.test.ts - Updated tests for dynamic import behavior (+206/-20)
docs/edge-runtime-process-once.md - Documentation for the fix (+73 lines)

Testing

Automated Tests

Unit tests added for Edge runtime behavior in AsyncTaskManager
Unit tests updated for cloud-price-updater dynamic import flow
Targeted coverage >= 90% for changed files

Verification

bun run build - No longer produces Edge Runtime process.once warnings
bun run lint - Passes
bun run typecheck - Passes
bun run test - Passes

Checklist

Code follows project conventions
Self-review completed
Tests pass locally
No breaking changes - only affects Edge/CI/build environments

Description enhanced by Claude AI

补充 NEXT_PHASE === "phase-production-build" 检查 Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>

coderabbitai · 2026-01-12T13:46:59Z

📝 Walkthrough

Walkthrough

本PR为Next.js引入了对边缘运行时的修复，防止构建期间出现process.once警告。核心改动包括：AsyncTaskManager添加延迟初始化逻辑在Edge环境下跳过初始化，cloud-price-updater将静态导入改为动态导入并添加Edge运行时短路处理，配合全面的单元测试覆盖。

Changes

核心 / 文件	变更摘要
文档 `docs/edge-runtime-process-once.md`	新增文档详细说明Edge Runtime process.once警告修复，包含复现步骤、实现细节、验证步骤和回滚指南
AsyncTaskManager延迟初始化 `src/lib/async-task-manager.ts`	引入私有initialized标志和initializeIfNeeded方法，在Edge/CI环境跳过Node特定初始化，register()调用时确保初始化执行
云价格同步运行时防护 `src/lib/price-sync/cloud-price-updater.ts`	添加Edge运行时短路、将静态AsyncTaskManager导入改为动态导入、新增全局scheduling标志防止并发重复调度、增强并发安全性和错误处理
AsyncTaskManager边缘运行时测试 `tests/unit/lib/async-task-manager-edge-runtime.test.ts`	新增308行全面的单元测试，覆盖Edge/Node运行时行为差异、任务生命周期、清理逻辑、取消处理和日志记录
云价格更新器集成测试 `tests/unit/price-sync/cloud-price-updater.test.ts`	扩展226行测试，新增运行时感知行为、动态导入检测、throttling验证、scheduling标志、并发控制和错误处理场景

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~65 minutes

Possibly related PRs

PR: 修复 Edge Runtime 下 process.once 构建告警（AsyncTaskManager 导入链） #589: 两个PR修改相同代码路径——均在AsyncTaskManager添加Edge/运行时守卫，并在cloud-price-updater中用动态运行时防护导入替换静态导入，以避免process.once警告。

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (2 warnings)

Check name	Status	Explanation	Resolution
Title check	⚠️ Warning	PR标题与实际变更内容产生了严重偏离。标题宣称修复「i18n 硬编码 + Next.js params Promise 报错」，但代码变更实际涉及 AsyncTaskManager、cloud-price-updater 等与 Edge Runtime 相关的优化，完全不涉及 usage-doc 或 big-screen 的国际化问题。	标题应准确反映实际代码变更内容。建议改为「fix: AsyncTaskManager 和 cloud-price-updater 的 Edge Runtime 兼容性」或「fix: Edge Runtime process.once 警告修复」等，以匹配具体的代码改动。
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description check	✅ Passed	PR描述清晰详细地解释了问题、解决方案和改动内容，与代码变更高度相关。

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing touches

📝 Generate docstrings

🧪 Generate unit tests (beta)

Create PR with unit tests
Post copyable unit tests in a comment

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

gemini-code-assist · 2026-01-12T13:47:02Z

Summary of Changes

Hello @YangQing-Lin, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

此拉取请求主要解决了 Next.js 应用在 Edge Runtime 环境下因使用 Node.js 专属 API (process.once) 导致的构建警告。通过对 AsyncTaskManager 进行条件初始化和在 cloud-price-updater 中引入动态导入，确保了代码在不同运行时环境下的兼容性。这些更改旨在提高应用的稳定性，减少构建时的潜在问题，并优化 Edge Runtime 的资源使用。

Highlights

修复 Edge Runtime process.once 警告: 通过在 Edge Runtime 环境下跳过 AsyncTaskManager 的初始化，解决了 next build 过程中出现的 process.once 不支持警告。
优化 cloud-price-updater 的 Edge Runtime 兼容性: 将 AsyncTaskManager 的静态导入改为动态导入，并在 Edge Runtime 环境下直接跳过价格同步逻辑，避免了不必要的模块加载和 Node.js API 调用。
增强测试覆盖: 新增了针对 AsyncTaskManager 在 Edge Runtime 和 Node.js 环境下行为的单元测试，并更新了 cloud-price-updater 的测试，以覆盖动态导入和错误处理场景。

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

这个 PR 的目标是解决在 Edge Runtime 中构建时出现的 process.once API 不支持的告警。您通过在 AsyncTaskManager 中实现懒加载初始化，并在 cloud-price-updater 中使用动态导入，成功地避免了在 Edge 环境中打包和执行 Node.js 专用的 API，这是一个非常清晰且有效的解决方案。

代码质量很高，主要变更点都伴随着全面且健壮的单元测试，这确保了新功能在 Edge 和 Node.js 环境下都能按预期工作，同时也保证了原有功能不受影响。此外，您还添加了详细的文档（docs/edge-runtime-process-once.md）来解释问题的背景、解决方案和验证步骤，这是非常好的实践，极大地提升了代码库的可维护性。

整体来看，这是一个高质量的修复，代码逻辑严谨，测试覆盖充分，文档清晰。我只发现一个可以简化测试代码的小建议。

请注意：本次审查是基于您提交的代码变更（Patch）进行的。PR 的标题和描述似乎与代码变更的内容不符（描述涉及 i18n 和 Next.js params 修复，而代码是关于 Edge Runtime 的修复）。建议您更新一下 PR 的描述以保持同步。

gemini-code-assist · 2026-01-12T13:48:47Z

tests/unit/price-sync/cloud-price-updater.test.ts

+    const prevRuntime = process.env.NEXT_RUNTIME;
+    process.env.NEXT_RUNTIME = "edge";
+
+    const { requestCloudPriceTableSync } = await import("@/lib/price-sync/cloud-price-updater");
+    requestCloudPriceTableSync({ reason: "missing-model", throttleMs: 0 });
+    await flushAsync();
+
+    expect(asyncTaskManagerLoaded).toBe(false);
+
+    process.env.NEXT_RUNTIME = prevRuntime;


为了提升测试代码的简洁性和可维护性，可以移除此处手动的 process.env.NEXT_RUNTIME 保存和恢复逻辑。外层的 describe 块已经通过 beforeEach 和 afterEach hook 对该环境变量进行了管理，afterEach 会在测试结束后自动恢复其原始值。移除冗余代码可以让测试意图更清晰。

Suggested change

const prevRuntime = process.env.NEXT_RUNTIME;

process.env.NEXT_RUNTIME = "edge";

const { requestCloudPriceTableSync } = await import("@/lib/price-sync/cloud-price-updater");

requestCloudPriceTableSync({ reason: "missing-model", throttleMs: 0 });

await flushAsync();

expect(asyncTaskManagerLoaded).toBe(false);

process.env.NEXT_RUNTIME = prevRuntime;

process.env.NEXT_RUNTIME = "edge";

const { requestCloudPriceTableSync } = await import("@/lib/price-sync/cloud-price-updater");

requestCloudPriceTableSync({ reason: "missing-model", throttleMs: 0 });

await flushAsync();

expect(asyncTaskManagerLoaded).toBe(false);

greptile-apps

_{3 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

greptile-apps · 2026-01-12T13:49:47Z

Additional Comments (1)

src/lib/price-sync/cloud-price-updater.ts
[P0] Scheduling flag never cleared on early returns, causing permanent lockout

The __CCH_CLOUD_PRICE_SYNC_SCHEDULING__ flag is set to true at line 82 but is only cleared in the finally block of the async IIFE (line 126). However, there are two early returns before the IIFE starts:

Line 74-76: Throttle check returns early
Line 79-81: Duplicate scheduling flag check returns early

If the throttle check passes initially (line 74) but then the scheduling flag is set (line 82), and then a second call comes in that hits the throttle check (line 74-76), the first call's flag will remain set but its IIFE never completes, permanently blocking all future sync attempts.

Scenario:

Call A: Passes throttle → sets flag → starts IIFE
Call B (concurrent): Passes throttle (before A updates timestamp) → sees flag set → returns early
Call C (later): Hits throttle check → returns early without clearing the flag
All future calls are now blocked forever

  // 避免并发请求在 AsyncTaskManager 加载前重复触发（例如多请求同时命中 missing-model）
  if (g.__CCH_CLOUD_PRICE_SYNC_SCHEDULING__) {
    return;
  }
  
  // NOTE: Flag must be cleared in the finally block starting at line 125
  // Do NOT add any early returns after this point without moving flag to separate scope
  g.__CCH_CLOUD_PRICE_SYNC_SCHEDULING__ = true;

The correct fix would be to move the scheduling flag check BEFORE the throttle check, or use a more sophisticated locking mechanism.

Prompt To Fix With AI

This is a comment left during a code review.
Path: src/lib/price-sync/cloud-price-updater.ts
Line: 78:82

Comment:
[P0] **Scheduling flag never cleared on early returns, causing permanent lockout**

The `__CCH_CLOUD_PRICE_SYNC_SCHEDULING__` flag is set to `true` at line 82 but is only cleared in the `finally` block of the async IIFE (line 126). However, there are two early returns before the IIFE starts:

1. Line 74-76: Throttle check returns early
2. Line 79-81: Duplicate scheduling flag check returns early

If the throttle check passes initially (line 74) but then the scheduling flag is set (line 82), and then a *second* call comes in that hits the throttle check (line 74-76), the first call's flag will remain set but its IIFE never completes, permanently blocking all future sync attempts.

**Scenario:**
- Call A: Passes throttle → sets flag → starts IIFE
- Call B (concurrent): Passes throttle (before A updates timestamp) → sees flag set → returns early
- Call C (later): **Hits throttle check** → returns early **without clearing the flag**
- **All future calls are now blocked forever**

```suggestion
  // 避免并发请求在 AsyncTaskManager 加载前重复触发（例如多请求同时命中 missing-model）
  if (g.__CCH_CLOUD_PRICE_SYNC_SCHEDULING__) {
    return;
  }
  
  // NOTE: Flag must be cleared in the finally block starting at line 125
  // Do NOT add any early returns after this point without moving flag to separate scope
  g.__CCH_CLOUD_PRICE_SYNC_SCHEDULING__ = true;
```

The correct fix would be to move the scheduling flag check BEFORE the throttle check, or use a more sophisticated locking mechanism.

How can I resolve this? If you propose a fix, please make it concise.

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (1)

src/lib/async-task-manager.ts (1)
29-49: 延迟初始化逻辑实现良好

环境守卫逻辑正确地跳过了 Edge/CI/生产构建环境下的 Node-only API 调用。不过，debug 日志中记录了 nextRuntime 和 ci，但遗漏了同样参与判断的 NEXT_PHASE。
建议在 debug 日志中补充 NEXT_PHASE
      logger.debug("[AsyncTaskManager] Skipping initialization in edge/CI environment", {
        nextRuntime: process.env.NEXT_RUNTIME,
        ci: process.env.CI,
+       nextPhase: process.env.NEXT_PHASE,
      });

📜 Review details

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Cache: Disabled due to Reviews > Disable Cache setting

📥 Commits

Reviewing files that changed from the base of the PR and between 8885884 and 65ae2aa.

📒 Files selected for processing (5)

docs/edge-runtime-process-once.md
src/lib/async-task-manager.ts
src/lib/price-sync/cloud-price-updater.ts
tests/unit/lib/async-task-manager-edge-runtime.test.ts
tests/unit/price-sync/cloud-price-updater.test.ts

🧰 Additional context used

📓 Path-based instructions (5)

**/*.{js,ts,tsx,jsx}