mini-three-adapter 0.1.6 → 0.1.8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/AGENTS.md +85 -85
  2. package/LICENSE +21 -21
  3. package/README.md +159 -159
  4. package/dist/build/rollup.d.ts +2 -2
  5. package/dist/build/rollup.js.map +1 -1
  6. package/dist/build/vite.d.ts +2 -2
  7. package/dist/build/vite.js.map +1 -1
  8. package/dist/{chunk-MSP7V7KM.js → chunk-DQH3YRGN.js} +3 -3
  9. package/dist/chunk-DQH3YRGN.js.map +1 -0
  10. package/dist/{chunk-35XVAVDB.js → chunk-J34MD3IL.js} +2 -2
  11. package/dist/chunk-J34MD3IL.js.map +1 -0
  12. package/dist/{chunk-LCJNTN6F.js → chunk-LAVHSWBU.js} +8 -5
  13. package/dist/chunk-LAVHSWBU.js.map +1 -0
  14. package/dist/{chunk-WYUHMKUM.js → chunk-RYWYBOYO.js} +43 -4
  15. package/dist/chunk-RYWYBOYO.js.map +1 -0
  16. package/dist/{chunk-6Y4MKIJL.js → chunk-SXQUZI22.js} +4 -4
  17. package/dist/chunk-SXQUZI22.js.map +1 -0
  18. package/dist/{chunk-TDVL2OAV.js → chunk-TPMMZFHW.js} +123 -58
  19. package/dist/chunk-TPMMZFHW.js.map +1 -0
  20. package/dist/{chunk-L4QZ5SP6.js → chunk-YPG3QUYK.js} +4 -4
  21. package/dist/chunk-YPG3QUYK.js.map +1 -0
  22. package/dist/core/index.d.ts +9 -3
  23. package/dist/core/index.js +3 -3
  24. package/dist/index.d.ts +2 -2
  25. package/dist/index.js +7 -7
  26. package/dist/platforms/browser.d.ts +2 -2
  27. package/dist/platforms/browser.js +4 -4
  28. package/dist/platforms/wechat-game.d.ts +2 -2
  29. package/dist/platforms/wechat-game.js +5 -5
  30. package/dist/platforms/wechat-miniprogram.d.ts +2 -2
  31. package/dist/platforms/wechat-miniprogram.js +5 -5
  32. package/dist/{plugin-core-BuqW9C-L.d.ts → plugin-core-CBOr1cyv.d.ts} +15 -4
  33. package/dist/polyfills/index.d.ts +1 -1
  34. package/dist/polyfills/index.js +1 -1
  35. package/dist/{runtime-BrHExTjl.d.ts → runtime-C8_xIlDM.d.ts} +29 -1
  36. package/dist/scope.d.ts +1 -1
  37. package/dist/scope.js +1 -1
  38. package/dist/{types-X_5SJh4y.d.ts → types-DOoJ7noL.d.ts} +13 -1
  39. package/docs/01-design-principles.md +105 -105
  40. package/docs/03-module-map.md +99 -99
  41. package/docs/04-api-reference.md +310 -304
  42. package/docs/05-build-plugin.md +176 -176
  43. package/docs/06-platform-notes.md +8 -4
  44. package/docs/07-integration-guide.md +226 -225
  45. package/docs/08-extension-guide.md +101 -101
  46. package/docs/09-testing-and-release.md +212 -211
  47. package/docs/11-compat-matrix.md +100 -100
  48. package/docs/README.md +41 -41
  49. package/docs/adr/0001-scoped-globals.md +41 -41
  50. package/docs/adr/0002-unified-runtime-lifecycle.md +40 -40
  51. package/docs/adr/0003-ast-rewrite.md +51 -51
  52. package/docs/adr/0004-in-place-patching.md +42 -42
  53. package/docs/adr/0005-webgl2-only.md +44 -44
  54. package/docs/adr/0006-zero-three-dependency.md +43 -43
  55. package/docs/adr/0007-capability-probe-fallback.md +61 -61
  56. package/docs/adr/0008-probe-fallback-boundary.md +56 -56
  57. package/docs/adr/0009-placeholder-scope-environment-globals.md +69 -69
  58. package/docs/adr/0010-native-event-target-boundary.md +82 -0
  59. package/docs/adr/0011-host-callback-slot-bridging.md +45 -0
  60. package/docs/adr/README.md +33 -31
  61. package/package.json +126 -125
  62. package/dist/chunk-35XVAVDB.js.map +0 -1
  63. package/dist/chunk-6Y4MKIJL.js.map +0 -1
  64. package/dist/chunk-L4QZ5SP6.js.map +0 -1
  65. package/dist/chunk-LCJNTN6F.js.map +0 -1
  66. package/dist/chunk-MSP7V7KM.js.map +0 -1
  67. package/dist/chunk-TDVL2OAV.js.map +0 -1
  68. package/dist/chunk-WYUHMKUM.js.map +0 -1
@@ -1,211 +1,212 @@
1
- # 09 · 测试、构建与发布
2
-
3
- ## 9.1 常用命令
4
-
5
- ```bash
6
- npm install # 安装依赖
7
- npm run typecheck # tsc --noEmit(strict)
8
- npm test # vitest run(82 例)
9
- npm test -- --watch # 观察模式
10
- npm run build # tsup:dist/*.js + *.d.ts + sourcemap
11
- npm run check # typecheck + test + build
12
- ```
13
-
14
- Windows 说明:`vitest.config.ts` 使用**单 fork**(`pool: 'forks'`, `singleFork: true`, `fileParallelism: false`, `cache: false`),避免并行 worker 写入系统临时目录时的 `EPERM`。若仍遇到临时目录权限问题:
15
-
16
- ```bash
17
- TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test
18
- ```
19
-
20
- ## 9.2 测试结构
21
-
22
- | 文件 | 覆盖 |
23
- | --- | --- |
24
- | `tests/scope-rewrite.test.ts` | AST 重写:自由变量、局部遮蔽、对象键、成员属性、`typeof`、import/export、自定义访问器 |
25
- | `tests/polyfills.test.ts` | EventTarget/once/remove、PointerEvent、Blob/URL/base64、URL 解析、TextEncoder、fetch、AbortController |
26
- | `tests/runtime.test.ts` | 画布补丁、scope 隔离、上下文缓存、触摸桥、多指、installGlobals 可逆、resize/dispose、能力报告 |
27
- | `tests/plugin.test.ts` | 资产扫描、未解析资源、模块过滤、WebGPU 告警、manifest 输出 |
28
- | `tests/image-events.test.ts` | 图片事件宿主矩阵:可写描述符 / 仅原生 `addEventListener` / 仅 `wx.getImageInfo` / 三者皆无的 2s watchdog;`complete` 与 `decode()` 的成功/失败语义;`src` 为数据属性时的写入;终态只派发一次;告警去重与宿主形状 payload |
29
- | `tests/event-dispatch.test.ts` | 监听器 `this`、`event.target` / `currentTarget` 指向宿主元素(含 three `ImageLoader` 取图场景)、`event.target` 不暴露内部监听表 |
30
- | `tests/capabilities.test.ts` | 离屏优先 / 无离屏 API 时不兜底 / 主画布回退 / 无法探测返回 `undefined`、`webgl2Source` 三态、回退拿到任一候选上屏画布时按身份放弃(含宿主显式传 `canvas` 的组合) |
31
- | `tests/scope.test.ts` | 未初始化占位作用域:环境全局读作 `undefined`、`typeof window.document` 不抛、真实 API 仍抛可读错误、早读被 `createRuntime()` 点名一次 |
32
- | `tests/helpers/mock-wx.ts` | 可注入的 `wx` 模拟器(`__setSize`、`__touch`、`__canvases`、`__images`) |
33
-
34
- **新功能必须带测试**。写测试时优先用 `createMockWx()` 注入,不要在测试里依赖真实 `wx` 或浏览器 DOM。
35
-
36
- ## 9.3 构建产物
37
-
38
- `tsup.config.ts` 有两套配置:
39
-
40
- | 配置 | 目标 | 输出 |
41
- | --- | --- | --- |
42
- | runtime | `es2019` / `platform: 'neutral'` / splitting / dts | `dist/index.js`、`dist/core/index.js`、`dist/scope.js`、`dist/polyfills/index.js`、`dist/platforms/*.js` + 共享 chunk |
43
- | build tooling | `node18` / `platform: 'node'` / 不 splitting / dts | `dist/build/vite.js`、`dist/build/rollup.js` |
44
-
45
- 要点:
46
-
47
- - `es2019` 让 esbuild 降级可选链与空值合并,减少开发者工具的语法报错。
48
- - `three` 被标记为 `external`,永远不会进适配层产物。
49
- - `sideEffects` 只声明平台入口文件,保证 tree-shaking 不误删必要的初始化。
50
- - `.d.ts` 由 tsup/dts 生成,`package.json` 的 `exports` 逐个子路径指向它们。
51
-
52
- 构建后冒烟:
53
-
54
- ```bash
55
- node --input-type=module -e "
56
- import { rewriteGlobals } from './dist/build/rollup.js';
57
- import { miniThree } from './dist/build/vite.js';
58
- import { createWeChatGameRuntime } from './dist/index.js';
59
- console.log(typeof rewriteGlobals, typeof miniThree, typeof createWeChatGameRuntime);
60
- "
61
- ```
62
-
63
- ## 9.4 建议的 CI 流程
64
-
65
- ```yaml
66
- # .github/workflows/ci.yml(示意)
67
- name: ci
68
- on: [push, pull_request]
69
- jobs:
70
- check:
71
- runs-on: ubuntu-latest
72
- steps:
73
- - uses: actions/checkout@v4
74
- - uses: actions/setup-node@v4
75
- with: { node-version: 20 }
76
- - run: npm ci
77
- - run: npm run check
78
- - name: Verify examples typecheck
79
- run: |
80
- cd examples/wechat-minigame && npm ci && npx tsc --noEmit -p tsconfig.json
81
- ```
82
-
83
- 额外建议:
84
-
85
- - 在 CI 中打印 `plugin.api.report()`,把 `parseFailures` / `missingAssets` 作为质量门禁(允许白名单)。
86
- - 建立回归用例集:按 controls / loaders / postprocessing / 动画 / 物理分类,每个类别挑选若干 three 官方示例场景,用 `examples/` 的三种平台工程跑通,结果写进 `docs/11-compat-matrix.md`。
87
-
88
- ## 9.5 发布到 npm
89
-
90
- ### 9.5.1 发布前检查
91
-
92
- ```bash
93
- npm run check # typecheck + 82 例测试 + tsup 构建
94
- npm run release:check # npm pack --dry-run --json,看将要发布的文件清单
95
- ```
96
-
97
- `package.json` 已配置 `prepublishOnly: "npm run clean && npm run check"`,`npm publish` 会自动清空 `dist/` 并跑一次完整构建与测试,既不会把未构建的产物发出去,也不会带入历史 hash chunk。发布前确认:
98
-
99
- - `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.5 实测 76 个文件、解包 687 KB、tarball 196 KB)。体积主要是 `docs/` 的 Markdown 与 `dist/` 的 `.d.ts`,两者都压缩率极高,tarball 增量很小。
100
- - 测体积前必须先 `npm run clean`(`release:check` 已包含),否则 `dist/` 里上一轮构建残留的 hash chunk 会被一起算进去,实测值会虚高。
101
- - `exports` 里每个子路径的 `.js` 与 `.d.ts` 都存在。
102
- - `CHANGELOG.md` 已补上本次版本条目。
103
- - `docs/04-api-reference.md` 与 `package.json exports` 一致;`docs/03-module-map.md` 与文件树一致。
104
- - `docs/11-compat-matrix.md` 已登记验证过的 three / 基础库版本。
105
-
106
- `package.json` 已配置 `repository` / `homepage` / `bugs`,npm 包页面会展示源码入口与 issue 链接。若仓库迁移,同步修改这三个字段后再发布。
107
-
108
- ### 9.5.2 准备 npm 账号
109
-
110
- 1. 在 [npmjs.com](https://www.npmjs.com/signup) 注册账号,并在 **Account → 2FA** 开启双因素认证。
111
- 2. 检查包名是否可用(发布前再查一次,避免被占用):
112
-
113
- ```bash
114
- npm view mini-three-adapter version
115
- # 404 Not Found = 可用
116
- ```
117
-
118
- 3. 登录:
119
-
120
- ```bash
121
- npm login # 浏览器授权,最简单
122
- npm whoami # 确认已登录
123
- ```
124
-
125
- CI 或非交互环境用 granular access token(权限选 `Read and write`,并限定到该包):
126
-
127
- ```bash
128
- # 不要把这个文件提交到仓库
129
- echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
130
- ```
131
-
132
- ### 9.5.3 本地演练(推荐先做)
133
-
134
- 生成一个真实 tarball,在干净目录里装一次,确认子路径导入都能解析:
135
-
136
- ```bash
137
- npm pack # 得到 mini-three-adapter-0.1.0.tgz
138
- mkdir -p /tmp/m3-smoke && cd /tmp/m3-smoke
139
- npm init -y && npm pkg set type=module
140
- npm i /path/to/mini-three-adapter-0.1.0.tgz three
141
- node --input-type=module -e "
142
- import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
143
- import { createWeChatMiniProgramRuntime } from 'mini-three-adapter/wechat-miniprogram';
144
- import miniThree from 'mini-three-adapter/vite';
145
- import { getActiveScope } from 'mini-three-adapter/scope';
146
- console.log(typeof createWeChatGameRuntime, typeof createWeChatMiniProgramRuntime, typeof miniThree, typeof getActiveScope);
147
- "
148
- ```
149
-
150
- > 未登录也能执行这一步。`npm pack` 生成的文件记得从仓库目录删掉,或把它加进 `.gitignore`。
151
-
152
- ### 9.5.4 正式发布
153
-
154
- ```bash
155
- npm publish --access public
156
- ```
157
-
158
- `publishConfig.access` 已设为 `public`,`--access public` 可省略。执行后 `prepublishOnly` 会自动清空 `dist/` 并跑 `npm run check`。
159
-
160
- **npm 的版本号不可覆盖**:同一个 `0.1.0` 只能发一次,之后每次改动都要先升版本再发。24 小时内可以 `npm unpublish <pkg>@<version>` 撤回,超过时间就不能删了;公开包一旦被他人依赖,撤回会影响别人,尽量不要依赖这个能力。
161
-
162
- ### 9.5.5 发布后验证
163
-
164
- ```bash
165
- npm view mini-three-adapter version
166
- npm view mini-three-adapter exports --json
167
- ```
168
-
169
- 在任意新项目里执行 `npm i mini-three-adapter three`,再跑一遍 9.5.3 的 import 冒烟。CDN 会在发布后自动可用(如 `https://unpkg.com/mini-three-adapter/`),但小游戏构建走本地 node_modules,不依赖 CDN。
170
-
171
- ### 9.5.6 后续版本
172
-
173
- ```bash
174
- # 修 bug
175
- npm version patch && npm publish
176
- # 新增向后兼容能力
177
- npm version minor && npm publish
178
- # 破坏性变更(0.x 阶段也用 minor 时要写进 CHANGELOG)
179
- npm version major && npm publish
180
- ```
181
-
182
- `npm version` 会自动改 `package.json`、生成 git tag(若已 `git init`)。每次发布重复 9.5.1 的检查。
183
-
184
- CI 自动发布(`.github/workflows/publish.yml`)要点:用 `actions/setup-node` 配置 `registry-url`,把 `NPM_TOKEN` 放在仓库 Secrets 里,在 `npm ci && npm run check` 之后执行 `npm publish --provenance --access public`。`--provenance` 会在 npm 页面生成来源证明,需要仓库为 public 且 workflow 具备 `id-token: write` 权限。
185
-
186
- ### 9.5.7 其他分发方式
187
-
188
- | 方式 | 适用场景 |
189
- | --- | --- |
190
- | `npm pack` 把 `.tgz` 直接发给同事 | 还没决定公开,或需要在隔离环境试用;对方 `npm i ./xxx.tgz` |
191
- | `"mini-three-adapter": "file:../.."` | 本机多个项目复用同一份源码 |
192
- | 私有 registry(Verdaccio / GitHub Packages) | 只给团队内部使用,不想发到公共 npm |
193
- | `npm link` | 开发期实时联调,改源码立刻生效 |
194
-
195
- 发布到公共 npm 之后,业务项目只需 `npm i mini-three-adapter three`,`examples/*/package.json` 里的 `workspace:*` 改成 `"^0.1.0"` 即可。
196
-
197
- ## 9.6 版本策略
198
-
199
- - 遵循语义化版本;`0.x` 阶段 minor 可含破坏性变更,但必须在 CHANGELOG 与接入文档里写明。
200
- - `three` 是 optional peer,`>=0.163.0`(WebGL2 门槛)。three 大版本升级时,重点回归 `DEFAULT_GLOBAL_NAMES` 与 `patchElement` 的属性集合。
201
- - 微信基础库能力变化只影响 `capabilities.ts` / `wechat-common.ts` / `assets.ts`,不应扩散到 `core/`。
202
-
203
- ## 9.7 真机验收清单(发布前)
204
-
205
- - [ ] iOS / Android 各一台,WebGL2 正常出图
206
- - [ ] 多指缩放/旋转(OrbitControls)不卡死,`touchcancel` 后指针计数归零
207
- - [ ] 横竖屏切换后 `resize` 生效,画面不变形
208
- - [ ] 前后台切换后帧循环恢复
209
- - [ ] DRACO / KTX2 资源加载(含分包预下载 Worker)
210
- - [ ] `runtime.dispose()` 后无残留监听、无内存持续增长
211
- - [ ] `runtime.report()` 无 WebGL2 告警
1
+ # 09 · 测试、构建与发布
2
+
3
+ ## 9.1 常用命令
4
+
5
+ ```bash
6
+ npm install # 安装依赖
7
+ npm run typecheck # tsc --noEmit(strict)
8
+ npm test # vitest run(100 例)
9
+ npm test -- --watch # 观察模式
10
+ npm run build # tsup:dist/*.js + *.d.ts + sourcemap
11
+ npm run check # typecheck + test + build
12
+ npm run verify:h5 # 真实 Chromium 里验证 H5 原生事件目标(需先 build,Playwright 可选)
13
+ ```
14
+
15
+ Windows 说明:`vitest.config.ts` 使用**单 fork**(`pool: 'forks'`, `singleFork: true`, `fileParallelism: false`, `cache: false`),避免并行 worker 写入系统临时目录时的 `EPERM`。若仍遇到临时目录权限问题:
16
+
17
+ ```bash
18
+ TMP="$PWD/.tmp/vitest" TEMP="$PWD/.tmp/vitest" npm test
19
+ ```
20
+
21
+ ## 9.2 测试结构
22
+
23
+ | 文件 | 覆盖 |
24
+ | --- | --- |
25
+ | `tests/scope-rewrite.test.ts` | AST 重写:自由变量、局部遮蔽、对象键、成员属性、`typeof`、import/export、自定义访问器 |
26
+ | `tests/polyfills.test.ts` | EventTarget/once/remove、PointerEvent、Blob/URL/base64、URL 解析、TextEncoder、fetch、AbortController |
27
+ | `tests/runtime.test.ts` | 画布补丁、scope 隔离、上下文缓存、触摸桥、多指、installGlobals 可逆、resize/dispose、能力报告 |
28
+ | `tests/plugin.test.ts` | 资产扫描、未解析资源、模块过滤、WebGPU 告警、manifest 输出 |
29
+ | `tests/image-events.test.ts` | 图片事件宿主矩阵:可写描述符 / 仅原生 `addEventListener` / 仅 `wx.getImageInfo` / 三者皆无的 2s watchdog;`complete` 与 `decode()` 的成功/失败语义;`src` 为数据属性时的写入;终态只派发一次;告警去重与宿主形状 payload |
30
+ | `tests/event-dispatch.test.ts` | 监听器 `this`、`event.target` / `currentTarget` 指向宿主元素(含 three `ImageLoader` 取图场景)、`event.target` 不暴露内部监听表 |
31
+ | `tests/capabilities.test.ts` | 离屏优先 / 无离屏 API 时不兜底 / 主画布回退 / 无法探测返回 `undefined`、`webgl2Source` 三态、回退拿到任一候选上屏画布时按身份放弃(含宿主显式传 `canvas` 的组合) |
32
+ | `tests/scope.test.ts` | 未初始化占位作用域:环境全局读作 `undefined`、`typeof window.document` 不抛、真实 API 仍抛可读错误、早读被 `createRuntime()` 点名一次 |
33
+ | `tests/helpers/mock-wx.ts` | 可注入的 `wx` 模拟器(`__setSize`、`__touch`、`__canvases`、`__images`) |
34
+
35
+ **新功能必须带测试**。写测试时优先用 `createMockWx()` 注入,不要在测试里依赖真实 `wx` 或浏览器 DOM。
36
+
37
+ ## 9.3 构建产物
38
+
39
+ `tsup.config.ts` 有两套配置:
40
+
41
+ | 配置 | 目标 | 输出 |
42
+ | --- | --- | --- |
43
+ | runtime | `es2019` / `platform: 'neutral'` / splitting / dts | `dist/index.js`、`dist/core/index.js`、`dist/scope.js`、`dist/polyfills/index.js`、`dist/platforms/*.js` + 共享 chunk |
44
+ | build tooling | `node18` / `platform: 'node'` / 不 splitting / dts | `dist/build/vite.js`、`dist/build/rollup.js` |
45
+
46
+ 要点:
47
+
48
+ - `es2019` 让 esbuild 降级可选链与空值合并,减少开发者工具的语法报错。
49
+ - `three` 被标记为 `external`,永远不会进适配层产物。
50
+ - `sideEffects` 只声明平台入口文件,保证 tree-shaking 不误删必要的初始化。
51
+ - `.d.ts` 由 tsup/dts 生成,`package.json` 的 `exports` 逐个子路径指向它们。
52
+
53
+ 构建后冒烟:
54
+
55
+ ```bash
56
+ node --input-type=module -e "
57
+ import { rewriteGlobals } from './dist/build/rollup.js';
58
+ import { miniThree } from './dist/build/vite.js';
59
+ import { createWeChatGameRuntime } from './dist/index.js';
60
+ console.log(typeof rewriteGlobals, typeof miniThree, typeof createWeChatGameRuntime);
61
+ "
62
+ ```
63
+
64
+ ## 9.4 建议的 CI 流程
65
+
66
+ ```yaml
67
+ # .github/workflows/ci.yml(示意)
68
+ name: ci
69
+ on: [push, pull_request]
70
+ jobs:
71
+ check:
72
+ runs-on: ubuntu-latest
73
+ steps:
74
+ - uses: actions/checkout@v4
75
+ - uses: actions/setup-node@v4
76
+ with: { node-version: 20 }
77
+ - run: npm ci
78
+ - run: npm run check
79
+ - name: Verify examples typecheck
80
+ run: |
81
+ cd examples/wechat-minigame && npm ci && npx tsc --noEmit -p tsconfig.json
82
+ ```
83
+
84
+ 额外建议:
85
+
86
+ - 在 CI 中打印 `plugin.api.report()`,把 `parseFailures` / `missingAssets` 作为质量门禁(允许白名单)。
87
+ - 建立回归用例集:按 controls / loaders / postprocessing / 动画 / 物理分类,每个类别挑选若干 three 官方示例场景,用 `examples/` 的三种平台工程跑通,结果写进 `docs/11-compat-matrix.md`。
88
+
89
+ ## 9.5 发布到 npm
90
+
91
+ ### 9.5.1 发布前检查
92
+
93
+ ```bash
94
+ npm run check # typecheck + 100 例测试 + tsup 构建
95
+ npm run release:check # npm pack --dry-run --json,看将要发布的文件清单
96
+ ```
97
+
98
+ `package.json` 已配置 `prepublishOnly: "npm run clean && npm run check"`,`npm publish` 会自动清空 `dist/` 并跑一次完整构建与测试,既不会把未构建的产物发出去,也不会带入历史 hash chunk。发布前确认:
99
+
100
+ - `files` 白名单只包含 `dist/`、`README.md`、`AGENTS.md`、`llms.txt`、`docs/`(0.1.8 实测 78 个文件、解包 746 KB、tarball 212 KB)。体积主要是 `docs/` 的 Markdown 与 `dist/` 的 `.d.ts`,两者都压缩率极高,tarball 增量很小。
101
+ - 测体积前必须先 `npm run clean`(`release:check` 已包含),否则 `dist/` 里上一轮构建残留的 hash chunk 会被一起算进去,实测值会虚高。
102
+ - `exports` 里每个子路径的 `.js` 与 `.d.ts` 都存在。
103
+ - `CHANGELOG.md` 已补上本次版本条目。
104
+ - `docs/04-api-reference.md` 与 `package.json exports` 一致;`docs/03-module-map.md` 与文件树一致。
105
+ - `docs/11-compat-matrix.md` 已登记验证过的 three / 基础库版本。
106
+
107
+ `package.json` 已配置 `repository` / `homepage` / `bugs`,npm 包页面会展示源码入口与 issue 链接。若仓库迁移,同步修改这三个字段后再发布。
108
+
109
+ ### 9.5.2 准备 npm 账号
110
+
111
+ 1. 在 [npmjs.com](https://www.npmjs.com/signup) 注册账号,并在 **Account → 2FA** 开启双因素认证。
112
+ 2. 检查包名是否可用(发布前再查一次,避免被占用):
113
+
114
+ ```bash
115
+ npm view mini-three-adapter version
116
+ # 404 Not Found = 可用
117
+ ```
118
+
119
+ 3. 登录:
120
+
121
+ ```bash
122
+ npm login # 浏览器授权,最简单
123
+ npm whoami # 确认已登录
124
+ ```
125
+
126
+ CI 或非交互环境用 granular access token(权限选 `Read and write`,并限定到该包):
127
+
128
+ ```bash
129
+ # 不要把这个文件提交到仓库
130
+ echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > .npmrc
131
+ ```
132
+
133
+ ### 9.5.3 本地演练(推荐先做)
134
+
135
+ 生成一个真实 tarball,在干净目录里装一次,确认子路径导入都能解析:
136
+
137
+ ```bash
138
+ npm pack # 得到 mini-three-adapter-0.1.0.tgz
139
+ mkdir -p /tmp/m3-smoke && cd /tmp/m3-smoke
140
+ npm init -y && npm pkg set type=module
141
+ npm i /path/to/mini-three-adapter-0.1.0.tgz three
142
+ node --input-type=module -e "
143
+ import { createWeChatGameRuntime } from 'mini-three-adapter/wechat-game';
144
+ import { createWeChatMiniProgramRuntime } from 'mini-three-adapter/wechat-miniprogram';
145
+ import miniThree from 'mini-three-adapter/vite';
146
+ import { getActiveScope } from 'mini-three-adapter/scope';
147
+ console.log(typeof createWeChatGameRuntime, typeof createWeChatMiniProgramRuntime, typeof miniThree, typeof getActiveScope);
148
+ "
149
+ ```
150
+
151
+ > 未登录也能执行这一步。`npm pack` 生成的文件记得从仓库目录删掉,或把它加进 `.gitignore`。
152
+
153
+ ### 9.5.4 正式发布
154
+
155
+ ```bash
156
+ npm publish --access public
157
+ ```
158
+
159
+ `publishConfig.access` 已设为 `public`,`--access public` 可省略。执行后 `prepublishOnly` 会自动清空 `dist/` 并跑 `npm run check`。
160
+
161
+ **npm 的版本号不可覆盖**:同一个 `0.1.0` 只能发一次,之后每次改动都要先升版本再发。24 小时内可以 `npm unpublish <pkg>@<version>` 撤回,超过时间就不能删了;公开包一旦被他人依赖,撤回会影响别人,尽量不要依赖这个能力。
162
+
163
+ ### 9.5.5 发布后验证
164
+
165
+ ```bash
166
+ npm view mini-three-adapter version
167
+ npm view mini-three-adapter exports --json
168
+ ```
169
+
170
+ 在任意新项目里执行 `npm i mini-three-adapter three`,再跑一遍 9.5.3 的 import 冒烟。CDN 会在发布后自动可用(如 `https://unpkg.com/mini-three-adapter/`),但小游戏构建走本地 node_modules,不依赖 CDN。
171
+
172
+ ### 9.5.6 后续版本
173
+
174
+ ```bash
175
+ # 修 bug
176
+ npm version patch && npm publish
177
+ # 新增向后兼容能力
178
+ npm version minor && npm publish
179
+ # 破坏性变更(0.x 阶段也用 minor 时要写进 CHANGELOG)
180
+ npm version major && npm publish
181
+ ```
182
+
183
+ `npm version` 会自动改 `package.json`、生成 git tag(若已 `git init`)。每次发布重复 9.5.1 的检查。
184
+
185
+ CI 自动发布(`.github/workflows/publish.yml`)要点:用 `actions/setup-node` 配置 `registry-url`,把 `NPM_TOKEN` 放在仓库 Secrets 里,在 `npm ci && npm run check` 之后执行 `npm publish --provenance --access public`。`--provenance` 会在 npm 页面生成来源证明,需要仓库为 public 且 workflow 具备 `id-token: write` 权限。
186
+
187
+ ### 9.5.7 其他分发方式
188
+
189
+ | 方式 | 适用场景 |
190
+ | --- | --- |
191
+ | `npm pack` 把 `.tgz` 直接发给同事 | 还没决定公开,或需要在隔离环境试用;对方 `npm i ./xxx.tgz` |
192
+ | `"mini-three-adapter": "file:../.."` | 本机多个项目复用同一份源码 |
193
+ | 私有 registry(Verdaccio / GitHub Packages) | 只给团队内部使用,不想发到公共 npm |
194
+ | `npm link` | 开发期实时联调,改源码立刻生效 |
195
+
196
+ 发布到公共 npm 之后,业务项目只需 `npm i mini-three-adapter three`,`examples/*/package.json` 里的 `workspace:*` 改成 `"^0.1.0"` 即可。
197
+
198
+ ## 9.6 版本策略
199
+
200
+ - 遵循语义化版本;`0.x` 阶段 minor 可含破坏性变更,但必须在 CHANGELOG 与接入文档里写明。
201
+ - `three` 是 optional peer,`>=0.163.0`(WebGL2 门槛)。three 大版本升级时,重点回归 `DEFAULT_GLOBAL_NAMES` 与 `patchElement` 的属性集合。
202
+ - 微信基础库能力变化只影响 `capabilities.ts` / `wechat-common.ts` / `assets.ts`,不应扩散到 `core/`。
203
+
204
+ ## 9.7 真机验收清单(发布前)
205
+
206
+ - [ ] iOS / Android 各一台,WebGL2 正常出图
207
+ - [ ] 多指缩放/旋转(OrbitControls)不卡死,`touchcancel` 后指针计数归零
208
+ - [ ] 横竖屏切换后 `resize` 生效,画面不变形
209
+ - [ ] 前后台切换后帧循环恢复
210
+ - [ ] DRACO / KTX2 资源加载(含分包预下载 Worker)
211
+ - [ ] `runtime.dispose()` 后无残留监听、无内存持续增长
212
+ - [ ] `runtime.report()` 无 WebGL2 告警