diff --git a/docs/project-memory/shared-memory/development-workflow.md b/docs/project-memory/shared-memory/development-workflow.md
index 36fbbe575..06a2ed208 100644
--- a/docs/project-memory/shared-memory/development-workflow.md
+++ b/docs/project-memory/shared-memory/development-workflow.md
@@ -24,6 +24,8 @@
 
 ## 开始前
 
+- worktree 复用 `node_modules` 时，测试与构建的 workspace alias 必须指向当前工作树源码，不能经依赖软链接读取另一工作树的共享包。遇到仅 worktree 出现的 JSX 编译错误时先核对解析路径，不用给组件补全局变量来掩盖错误来源。
+
 - 运行 `git status --short`，保留用户已有的未提交修改；不要在共享工作树中使用破坏性 Git 命令。
 - 复杂任务先读 `AGENTS.md`、`docs/【协作规范】Agent工作入口与执行准则-2026-06-22.md`、`docs/README.md` 和对应专题。
 - 需要完整 SDD 的任务先确认主规范位置和验收证据，再创建 `docs/project-memory/plans/` 下的里程碑规范与实现计划；计划完成、取消或合并后删除。
diff --git a/vitest.config.ts b/vitest.config.ts
index 4d6d56888..e872c8c64 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -22,6 +22,26 @@ export default defineConfig({
       },
       // Keep shared components' application-root imports resolvable in tests.
       { find: '@', replacement: path.resolve(__dirname, '.') },
+      // worktree 复用依赖时，共享包仍须解析到当前检出的源码。
+      {
+        find: '@genarrative/shared/components/account',
+        replacement: path.resolve(
+          __dirname,
+          'packages/shared/src/components/account.ts',
+        ),
+      },
+      {
+        find: '@genarrative/shared/components',
+        replacement: path.resolve(__dirname, 'packages/shared/src/components'),
+      },
+      {
+        find: '@genarrative/shared/lib',
+        replacement: path.resolve(__dirname, 'packages/shared/src/lib'),
+      },
+      {
+        find: /^@genarrative\/shared$/,
+        replacement: path.resolve(__dirname, 'packages/shared/src/index.ts'),
+      },
       {
         find: '@genarrative/image-canvas-core',
         replacement: path.resolve(