From d8e0095a2881a066b4a4b8230644bbb979421b81 Mon Sep 17 00:00:00 2001
From: wc24 <wc24@qq.com>
Date: Sat, 23 May 2026 17:18:47 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20bump=20install=20snippet=20to=20v0.3.0?=
 =?UTF-8?q?=20+=20=E5=8A=A0=20ts-node/tsc=20=E9=85=8D=E7=BD=AE=E8=AF=B4?=
 =?UTF-8?q?=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

迁移 hand-server-2 时撞到两个坑,补到 README:
  - ts-node 默认 ignore node_modules,要在 tsconfig 加 "ts-node": { "ignore": ["(?!)"] }
  - tsc 默认 moduleResolution "node" 不读 exports 字段,要升 node16 或加 paths
---
 README.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 49 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 03881dc..6027611 100644
--- a/README.md
+++ b/README.md
@@ -6,14 +6,61 @@
 
 ```sh
 # 推荐: HTTP(任何能访问 git.zeromvc.com 的机器都能用)
-npm install git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.2.0
+npm install git+http://git.zeromvc.com/wc24/shrimp-server.git#v0.3.0
 
 # 也可以 SSH(需要 ssh key 配好)
-npm install git+ssh://git@git.zeromvc.com:wc24/shrimp-server.git#v0.2.0
+npm install git+ssh://git@git.zeromvc.com:wc24/shrimp-server.git#v0.3.0
 ```
 
 > 仓库 ship `.ts` 源码,消费方项目需要 TS 运行器(`tsx` / `ts-node`)或在打包工具(vite / webpack / esbuild)里能解析 `.ts`。
 
+### ts-node / ts-node-dev 用户:让它编译 node_modules 内的 .ts
+
+`ts-node` 默认会把 `node_modules/` 当成"已编译"跳过,直接把 shrimp-server 的 `.ts`
+源码丢给 Node — Node 22+ 看到 `export` 会按 ESM 加载然后炸 `Unexpected token 'export'`。
+在 `tsconfig.json` 里把 ignore 覆盖掉:
+
+```jsonc
+{
+    "compilerOptions": { /* ... */ },
+    "ts-node": {
+        // 默认是 /(?:^|/)node_modules// — 这里清空,让 ts-node 也编译 shrimp-server
+        "ignore": ["(?!)"]
+    }
+}
+```
+
+`tsx` 用户不需要这一步(tsx 默认就编译 node_modules 内的 .ts)。
+
+### TypeScript 用户:让 tsc 识别 `shrimp-server/server` 子路径
+
+包用 package.json `exports` 字段划分了 `'shrimp-server'`(0 重依赖核心)和
+`'shrimp-server/server'`(Express 装配体)两个入口。**TS 默认的 `moduleResolution: "node"`
+不读 `exports`,会找不到子路径模块。** 两个解法二选一:
+
+```jsonc
+// 方案 A: 升 moduleResolution(配合 module: node16,严格但纯净)
+"compilerOptions": {
+    "module": "node16",
+    "moduleResolution": "node16"
+}
+```
+
+```jsonc
+// 方案 B: 保留 commonjs,显式 paths 指过去(兼容 ts-node-dev 老版)
+"compilerOptions": {
+    "module": "commonjs",
+    "baseUrl": ".",
+    "paths": {
+        "shrimp-server": ["node_modules/shrimp-server/src/core.ts"],
+        "shrimp-server/server": ["node_modules/shrimp-server/src/server/index.ts"]
+    }
+}
+```
+
+Node 22+ 的 CJS 加载器 **会**读 `exports`,所以运行时不需要额外配置 — 只是 TS 的
+类型解析在 `moduleResolution: "node"` 模式下落后于 Node 实际行为,需要 paths 兜底。
+
 ### 两个入口,按需选择
 
 包内提供了**核心**和**完整 server** 两个 entry,**peer deps 全部 optional**——你只装自己用得到的那一份: