docs(skill): plugin bundle pipeline v2 (IIFE/多资产/热更新) 文档入仓

2026-10-14 00:20:56 +00:00
parent c9694511a1
commit a3fa01e25f
8 changed files with 338 additions and 130 deletions
@@ -104,3 +104,46 @@ If you're setting up the webpack config manually, make sure:
 - The plugin does NOT need `import React from 'react'` at the top when using
  `react-jsx` transform — JSX is auto-transpiled. But you still need
  `const React = host.React` for any explicit `React.createElement` calls.
+
+## Pitfall 8: Chunk 404 at runtime — multipart strips directory names (2026-10)
+
+`webpack output.chunkFilename: 'static/js/[name].chunk.js'` builds fine, the
+upload succeeds, but the browser 404s the chunk: multer/busboy flattens
+multipart filenames, so the server stored `469.chunk.js` while the bundle
+requests `static/js/469.chunk.js`.
+
+**Fix**: keep chunk names FLAT — `chunkFilename: '[name]-[contenthash].chunk.js'`
+(contenthash prevents collisions). Public path still works:
+`output.publicPath: '/api/plugin/<id>/runtime/'`.
+
+## Pitfall 9: `Bundle must be IIFE format` after a successful build
+
+Three producer-side causes, all seen in the wild:
+1. **Terser license banner** — bundling any npm package with license comments
+   makes webpack emit `/*! For license information... */` BEFORE `!function`.
+   Fix: `optimization.minimizer: [new TerserPlugin({ extractComments: false })]`.
+2. **Development-mode webpack** output starts with `/******/` banner comments.
+   The dev watch loop therefore builds with `--mode production`.
+3. **Vite/esbuild IIFE** output starts `var <name>=(function...` — the
+   validator accepts it (since 2026-10); no post-processing needed.
+
+## Pitfall 10: vite scaffold `pnpm install` fails with ERR_PNPM_IGNORED_BUILDS
+
+pnpm ≥ 10/11 blocks esbuild's postinstall and (on patched hosts) treats it as
+fatal. Fix (scaffold generates it): `pnpm-workspace.yaml` with
+`allowBuilds:\n  esbuild: true`. esbuild also works without its script (binary
+comes from optionalDependencies) — only the pnpm gate needs the allow entry.
+
+## Pitfall 11: PAT gets 403 fetching `/api/plugin/:id/runtime/*`
+
+Access tokens only pass routes with `@TokenAccess()` or `@Permissions` — the
+runtime asset serving has neither. This is by design (the browser loads with a
+session). For curl verification use a signed `auth_session` cookie; for uploads
+use the PAT (`upload-bundle` and `POST /api/plugin` are token-accessible).
+
+## Pitfall 12: "react/jsx-runtime would duplicate React" worry
+
+It does not. The jsx automatic transform imports `react/jsx-runtime`, which is
+bundled into the plugin on purpose: it only creates plain element objects.
+Hooks/context/state go through the externalized `react` → host singleton. This
+is exactly how the deployed ticket-console/batch-edit-pro bundles behave.