From 75e057ae7105c58bd9d1e162f367a1c95b2edf68 Mon Sep 17 00:00:00 2001
From: XGHeaven <xgheaven@gmail.com>
Date: Tue, 21 Apr 2026 20:47:24 +0800
Subject: [PATCH] feat: update v2 docs and support declaration.allowJs

---
 .changeset/migrate-generate-types-for-js.md   |   5 +
 packages/pkg/src/config/schema.ts             |   2 +-
 packages/pkg/src/config/userConfig.ts         |   4 -
 packages/pkg/src/core/init.ts                 |   2 +
 packages/pkg/src/helpers/dts.ts               |   4 +-
 packages/pkg/src/tasks/declaration.ts         |   6 +-
 packages/pkg/src/types.ts                     |  13 +-
 pnpm-lock.yaml                                |  49 +-
 website/docs/ai.md                            |  13 +
 website/docs/cli.md                           |  31 +
 website/docs/config/alias.md                  |  20 +
 website/docs/config/bundle.md                 | 239 ++++++
 website/docs/config/declaration.md            |  75 ++
 website/docs/config/define.md                 |  45 ++
 website/docs/config/entry.md                  |  32 +
 website/docs/config/helpers.md                |  34 +
 website/docs/config/index.md                  |  38 +
 website/docs/config/jsx-runtime.md            |  36 +
 website/docs/config/pkgs.md                   | 125 +++
 website/docs/config/plugins.md                |  21 +
 website/docs/config/server.md                 | 144 ++++
 website/docs/config/source-maps.md            |  24 +
 website/docs/config/transform.md              | 115 +++
 website/docs/guide/build-modes.md             | 211 ++++++
 website/docs/guide/build.md                   | 288 +++++--
 website/docs/guide/configure.md               |  58 ++
 website/docs/guide/css.md                     |  93 +++
 website/docs/guide/engine.md                  |  96 +++
 website/docs/guide/jsx-plus.md                |  30 +-
 website/docs/guide/mf.md                      |   2 +-
 website/docs/guide/monorepo.md                | 163 +---
 website/docs/guide/preview.md                 |  74 +-
 website/docs/guide/scenario/library.md        |  56 ++
 website/docs/guide/scenario/node.md           |  40 +
 website/docs/guide/scenario/react.md          | 159 ++++
 website/docs/guide/server.md                  |  15 +
 website/docs/guide/test.md                    | 199 +----
 website/docs/guide/typescript.md              | 121 +++
 website/docs/index.md                         |  51 +-
 website/docs/migration/v1-to-v2.md            | 145 ++++
 website/docs/plugin/development.md            | 629 +++++++++++++++
 website/docs/plugin/usage.md                  |  84 +++
 website/docs/quick-start.md                   |  30 +-
 website/docs/reference/cli.md                 |  29 -
 website/docusaurus.config.ts                  |  61 +-
 website/package.json                          |   1 +
 website/sidebars.js                           |  75 +-
 website/versioned_docs/version-v1/faq.md      |  36 +
 .../version-v1}/guide/Button.tsx              |   0
 .../version-v1}/guide/abilities.md            |   9 +-
 .../versioned_docs/version-v1/guide/build.md  | 192 +++++
 .../version-v1/guide/jsx-plus.md              | 171 +++++
 .../version-v1/guide/monorepo.md              | 229 ++++++
 .../version-v1/guide/preview.md               | 713 ++++++++++++++++++
 .../version-v1}/guide/publish.md              |  11 +-
 .../version-v1}/guide/scenarios.md            |  47 +-
 .../versioned_docs/version-v1/guide/test.md   | 257 +++++++
 website/versioned_docs/version-v1/index.md    |  52 ++
 .../versioned_docs/version-v1/quick-start.md  |  74 ++
 .../version-v1/reference/cli.md               |  29 +
 .../version-v1}/reference/config.md           |  76 +-
 .../reference/plugins-development.md          |  20 +-
 .../version-v1-sidebars.json                  |  24 +
 website/versions.json                         |   1 +
 64 files changed, 5072 insertions(+), 656 deletions(-)
 create mode 100644 .changeset/migrate-generate-types-for-js.md
 create mode 100644 website/docs/ai.md
 create mode 100644 website/docs/cli.md
 create mode 100644 website/docs/config/alias.md
 create mode 100644 website/docs/config/bundle.md
 create mode 100644 website/docs/config/declaration.md
 create mode 100644 website/docs/config/define.md
 create mode 100644 website/docs/config/entry.md
 create mode 100644 website/docs/config/helpers.md
 create mode 100644 website/docs/config/index.md
 create mode 100644 website/docs/config/jsx-runtime.md
 create mode 100644 website/docs/config/pkgs.md
 create mode 100644 website/docs/config/plugins.md
 create mode 100644 website/docs/config/server.md
 create mode 100644 website/docs/config/source-maps.md
 create mode 100644 website/docs/config/transform.md
 create mode 100644 website/docs/guide/build-modes.md
 create mode 100644 website/docs/guide/configure.md
 create mode 100644 website/docs/guide/css.md
 create mode 100644 website/docs/guide/engine.md
 create mode 100644 website/docs/guide/scenario/library.md
 create mode 100644 website/docs/guide/scenario/node.md
 create mode 100644 website/docs/guide/scenario/react.md
 create mode 100644 website/docs/guide/server.md
 create mode 100644 website/docs/guide/typescript.md
 create mode 100644 website/docs/migration/v1-to-v2.md
 create mode 100644 website/docs/plugin/development.md
 create mode 100644 website/docs/plugin/usage.md
 delete mode 100644 website/docs/reference/cli.md
 create mode 100644 website/versioned_docs/version-v1/faq.md
 rename website/{docs => versioned_docs/version-v1}/guide/Button.tsx (100%)
 rename website/{docs => versioned_docs/version-v1}/guide/abilities.md (93%)
 create mode 100644 website/versioned_docs/version-v1/guide/build.md
 create mode 100644 website/versioned_docs/version-v1/guide/jsx-plus.md
 create mode 100644 website/versioned_docs/version-v1/guide/monorepo.md
 create mode 100644 website/versioned_docs/version-v1/guide/preview.md
 rename website/{docs => versioned_docs/version-v1}/guide/publish.md (96%)
 rename website/{docs => versioned_docs/version-v1}/guide/scenarios.md (87%)
 create mode 100644 website/versioned_docs/version-v1/guide/test.md
 create mode 100644 website/versioned_docs/version-v1/index.md
 create mode 100644 website/versioned_docs/version-v1/quick-start.md
 create mode 100644 website/versioned_docs/version-v1/reference/cli.md
 rename website/{docs => versioned_docs/version-v1}/reference/config.md (84%)
 rename website/{docs => versioned_docs/version-v1}/reference/plugins-development.md (87%)
 create mode 100644 website/versioned_sidebars/version-v1-sidebars.json
 create mode 100644 website/versions.json

diff --git a/.changeset/migrate-generate-types-for-js.md b/.changeset/migrate-generate-types-for-js.md
new file mode 100644
index 00000000..3ee2f38d
--- /dev/null
+++ b/.changeset/migrate-generate-types-for-js.md
@@ -0,0 +1,5 @@
+---
+'@ice/pkg': major
+---
+
+feat: migrate `generateTypesForJs` to `declaration.allowJs`
diff --git a/packages/pkg/src/config/schema.ts b/packages/pkg/src/config/schema.ts
index e78ae393..7d1481e5 100644
--- a/packages/pkg/src/config/schema.ts
+++ b/packages/pkg/src/config/schema.ts
@@ -59,7 +59,6 @@ export const userConfigSchema = z.object({
     .record(z.string(), z.union([z.string(), z.boolean(), z.number(), z.null(), z.record(z.string(), z.any())]))
     .optional(),
   sourceMaps: z.union([z.boolean(), z.enum(['inline'])]).optional(),
-  generateTypeForJs: z.boolean().optional(),
   jsxRuntime: z.enum(['classic', 'automatic']).optional(),
   plugins: z.any().array().optional(),
   helpers: z.enum(['external', 'inline']).optional(),
@@ -71,6 +70,7 @@ export const userConfigSchema = z.object({
     z.object({
       outputMode: z.enum(['multi', 'unique']).optional(),
       generator: z.enum(['tsc', 'oxc']).optional(),
+      allowJs: z.boolean().optional(),
     }),
   ]),
   server: z.union([z.boolean(), serverSchema]).optional(),
diff --git a/packages/pkg/src/config/userConfig.ts b/packages/pkg/src/config/userConfig.ts
index 1c5665d1..b05800cf 100644
--- a/packages/pkg/src/config/userConfig.ts
+++ b/packages/pkg/src/config/userConfig.ts
@@ -24,10 +24,6 @@ function getUserConfig() {
       name: 'jsxRuntime',
       defaultValue: 'automatic',
     },
-    {
-      name: 'generateTypesForJs',
-      defaultValue: false,
-    },
     {
       name: 'declaration',
       defaultValue: true,
diff --git a/packages/pkg/src/core/init.ts b/packages/pkg/src/core/init.ts
index 7d114762..21600c80 100644
--- a/packages/pkg/src/core/init.ts
+++ b/packages/pkg/src/core/init.ts
@@ -28,6 +28,7 @@ const defaultBundleUserConfig: BundleUserConfig = {
 const defaultDeclarationUserConfig = {
   outputMode: 'multi',
   generator: 'tsc',
+  allowJs: false,
 } satisfies DeclarationUserConfig;
 
 export function initContextTasks(ctx: Context) {
@@ -159,6 +160,7 @@ export function initDeclarationTask(buildTask: BuildTask, options: InitTaskOptio
   } else {
     config.outputMode ??= declarationConfig?.outputMode ?? defaultDeclarationUserConfig.outputMode;
     config.generator ??= declarationConfig?.generator ?? defaultDeclarationUserConfig.generator;
+    config.allowJs ??= declarationConfig?.allowJs ?? defaultDeclarationUserConfig.allowJs;
   }
 
   const allOutputDirs = allTasks
diff --git a/packages/pkg/src/helpers/dts.ts b/packages/pkg/src/helpers/dts.ts
index 2fd2bc7e..ef61923d 100644
--- a/packages/pkg/src/helpers/dts.ts
+++ b/packages/pkg/src/helpers/dts.ts
@@ -47,6 +47,7 @@ export interface DtsCompileOptions {
   rootDir: string;
   outputDir: string;
   usingOxc: boolean;
+  allowJs?: boolean;
 }
 
 function formatAliasToTSPathsConfig(alias: TaskConfig['alias']) {
@@ -79,6 +80,7 @@ export async function dtsCompile({
   outputDir,
   alias,
   usingOxc,
+  allowJs = false,
 }: DtsCompileOptions): Promise<DtsInputFile[]> {
   if (!files.length) {
     return [];
@@ -88,7 +90,7 @@ export async function dtsCompile({
 
   const defaultTSConfig: TsConfigJson = {
     compilerOptions: {
-      allowJs: true,
+      allowJs,
       declaration: true,
       emitDeclarationOnly: true,
       incremental: true,
diff --git a/packages/pkg/src/tasks/declaration.ts b/packages/pkg/src/tasks/declaration.ts
index 80a3331f..a69d0359 100644
--- a/packages/pkg/src/tasks/declaration.ts
+++ b/packages/pkg/src/tasks/declaration.ts
@@ -33,9 +33,12 @@ class DeclarationRunner extends Runner<OutputResult> {
         context.buildContext.rootDir,
         (context.buildTask.config.entry! as Record<string, string>) ?? {},
       );
+      const filePattern = (context.buildTask.config as DeclarationTaskConfig).allowJs
+        ? '**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}'
+        : '**/*.{ts,tsx,mts,cts}';
       const result = await Promise.all(
         entryDirs.map((entry) =>
-          globby('**/*.{ts,tsx,mts,cts}', {
+          globby(filePattern, {
             cwd: entry,
             onlyFiles: true,
             ignore: ['**/*.d.{ts,mts,cts}'],
@@ -64,6 +67,7 @@ class DeclarationRunner extends Runner<OutputResult> {
         outputDir: buildConfig.outputDir!,
         alias: buildConfig.alias,
         usingOxc: buildConfig.generator === 'oxc',
+        allowJs: buildConfig.allowJs ?? false,
       },
     ]);
 
diff --git a/packages/pkg/src/types.ts b/packages/pkg/src/types.ts
index 486e050c..84a8bc22 100644
--- a/packages/pkg/src/types.ts
+++ b/packages/pkg/src/types.ts
@@ -176,6 +176,13 @@ export interface DeclarationUserConfig {
    * @default 'tsc'
    */
   generator?: 'tsc' | 'oxc';
+
+  /**
+   * Whether to generate declaration files for JavaScript files.
+   * Useful when using JSDoc type annotations in JS files.
+   * @default false
+   */
+  allowJs?: boolean;
 }
 
 export interface PkgUserConfig
@@ -278,12 +285,6 @@ export interface UserConfig {
    * but not include it in the result object.
    */
   sourceMaps?: boolean | 'inline';
-  /**
-   * Whether or not to generate declaration files for Ecmascript
-   * @default false
-   */
-  generateTypesForJs?: boolean;
-
   /**
    * Generate .d.ts files from TypeScript files in your project.
    * @default true
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 8ea72d1f..e25b15cb 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -46,7 +46,7 @@ importers:
         version: 20.19.25
       '@vitest/coverage-v8':
         specifier: 'catalog:'
-        version: 4.0.8(vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1))
+        version: 4.0.8(vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3))
       axios:
         specifier: ^0.23.0
         version: 0.23.0
@@ -85,7 +85,7 @@ importers:
         version: 5.9.2
       vitest:
         specifier: 'catalog:'
-        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
 
   examples/application:
     dependencies:
@@ -192,7 +192,7 @@ importers:
         version: 29.0.5(@babel/core@7.28.5)(@jest/types@29.4.3)(babel-jest@29.4.3(@babel/core@7.28.5))(jest@29.4.3(@types/node@20.19.25)(ts-node@10.8.2(@swc/core@1.15.7(@swc/helpers@0.5.17))(@types/node@20.19.25)(typescript@5.9.2)))(typescript@5.9.2)
       vitest:
         specifier: 'catalog:'
-        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
 
   examples/react-multi-components:
     dependencies:
@@ -358,7 +358,7 @@ importers:
         version: 5.9.2
       vitest:
         specifier: 'catalog:'
-        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+        version: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
 
   packages/pkg:
     dependencies:
@@ -748,6 +748,9 @@ importers:
       '@types/react':
         specifier: ^18.0.0
         version: 18.0.15
+      docusaurus-plugin-llms:
+        specifier: ^0.3.1
+        version: 0.3.1(@docusaurus/core@3.9.2(@mdx-js/react@3.1.1(@types/react@18.0.15)(react@18.2.0))(@rspack/core@1.3.12(@swc/helpers@0.5.17))(@swc/core@1.15.7(@swc/helpers@0.5.17))(react-dom@18.2.0(react@18.2.0))(react@18.2.0)(typescript@5.9.2))
       typescript:
         specifier: 'catalog:'
         version: 5.9.2
@@ -5377,6 +5380,12 @@ packages:
     resolution: {integrity: sha512-35mSku4ZXK0vfCuHEDAwt55dg2jNajHZ1odvF+8SSr82EsZY4QmXfuWso8oEd8zRhVObSN18aM0CjSdoBX7zIw==}
     engines: {node: '>=0.10.0'}
 
+  docusaurus-plugin-llms@0.3.1:
+    resolution: {integrity: sha512-2RsDC4czy1pt2kauIACOcLvSaGmjF3X0pgcVtL6fblzzZMgkasQJrOLN0pRur11j7rQkiaiCGR9NsU3mp4M8fg==}
+    engines: {node: '>=18.0'}
+    peerDependencies:
+      '@docusaurus/core': ^3.0.0
+
   dom-accessibility-api@0.5.16:
     resolution: {integrity: sha512-X7BJ2yElsnOJ30pZF4uIIDfBEVgF4XEBxL9Bxhy6dnrm5hkzqmsWHGTiHqRiITNhMyFLyAiWndIJP7Z1NTteDg==}
 
@@ -10916,6 +10925,11 @@ packages:
     engines: {node: '>= 14'}
     hasBin: true
 
+  yaml@2.8.3:
+    resolution: {integrity: sha512-AvbaCLOO2Otw/lW5bmh9d/WEdcDFdQp2Z2ZUH3pX9U2ihyUY0nvLv7J6TrWowklRGPYbB/IuIMfYgxaCPg5Bpg==}
+    engines: {node: '>= 14.6'}
+    hasBin: true
+
   yargs-parser@18.1.3:
     resolution: {integrity: sha512-o50j0JeToy/4K6OZcaQmW6lyXXKhq7csREXcDwk2omFPJEwUNOVtJKvmDr9EI1fAJZUyZcRF7kxGBWmRXudrCQ==}
     engines: {node: '>=6'}
@@ -15266,7 +15280,7 @@ snapshots:
 
   '@vercel/oidc@3.0.3': {}
 
-  '@vitest/coverage-v8@4.0.8(vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1))':
+  '@vitest/coverage-v8@4.0.8(vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3))':
     dependencies:
       '@bcoe/v8-coverage': 1.0.2
       '@vitest/utils': 4.0.8
@@ -15279,7 +15293,7 @@ snapshots:
       magicast: 0.5.1
       std-env: 3.10.0
       tinyrainbow: 3.0.3
-      vitest: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+      vitest: 4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
     transitivePeerDependencies:
       - supports-color
 
@@ -15292,13 +15306,13 @@ snapshots:
       chai: 6.2.1
       tinyrainbow: 3.0.3
 
-  '@vitest/mocker@4.0.8(vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1))':
+  '@vitest/mocker@4.0.8(vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3))':
     dependencies:
       '@vitest/spy': 4.0.8
       estree-walker: 3.0.3
       magic-string: 0.30.21
     optionalDependencies:
-      vite: 7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+      vite: 7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
 
   '@vitest/pretty-format@4.0.8':
     dependencies:
@@ -16803,6 +16817,13 @@ snapshots:
     dependencies:
       esutils: 2.0.3
 
+  docusaurus-plugin-llms@0.3.1(@docusaurus/core@3.9.2(@mdx-js/react@3.1.1(@types/react@18.0.15)(react@18.2.0))(@rspack/core@1.3.12(@swc/helpers@0.5.17))(@swc/core@1.15.7(@swc/helpers@0.5.17))(react-dom@18.2.0(react@18.2.0))(react@18.2.0)(typescript@5.9.2)):
+    dependencies:
+      '@docusaurus/core': 3.9.2(@mdx-js/react@3.1.1(@types/react@18.0.15)(react@18.2.0))(@rspack/core@1.3.12(@swc/helpers@0.5.17))(@swc/core@1.15.7(@swc/helpers@0.5.17))(debug@4.4.3)(react-dom@18.2.0(react@18.2.0))(react@18.2.0)(typescript@5.9.2)
+      gray-matter: 4.0.3
+      minimatch: 9.0.5
+      yaml: 2.8.3
+
   dom-accessibility-api@0.5.16: {}
 
   dom-converter@0.2.0:
@@ -23107,7 +23128,7 @@ snapshots:
       '@types/unist': 3.0.3
       vfile-message: 4.0.3
 
-  vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1):
+  vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3):
     dependencies:
       esbuild: 0.25.12
       fdir: 6.5.0(picomatch@4.0.3)
@@ -23123,12 +23144,12 @@ snapshots:
       sass: 1.94.0
       sass-embedded: 1.89.2
       terser: 5.44.1
-      yaml: 2.7.1
+      yaml: 2.8.3
 
-  vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1):
+  vitest@4.0.8(@types/debug@4.1.12)(@types/node@20.19.25)(jiti@2.4.2)(jsdom@21.1.0)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3):
     dependencies:
       '@vitest/expect': 4.0.8
-      '@vitest/mocker': 4.0.8(vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1))
+      '@vitest/mocker': 4.0.8(vite@7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3))
       '@vitest/pretty-format': 4.0.8
       '@vitest/runner': 4.0.8
       '@vitest/snapshot': 4.0.8
@@ -23145,7 +23166,7 @@ snapshots:
       tinyexec: 0.3.2
       tinyglobby: 0.2.15
       tinyrainbow: 3.0.3
-      vite: 7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.7.1)
+      vite: 7.2.2(@types/node@20.19.25)(jiti@2.4.2)(less@4.1.3)(sass-embedded@1.89.2)(sass@1.94.0)(terser@5.44.1)(yaml@2.8.3)
       why-is-node-running: 2.3.0
     optionalDependencies:
       '@types/debug': 4.1.12
@@ -23547,6 +23568,8 @@ snapshots:
 
   yaml@2.7.1: {}
 
+  yaml@2.8.3: {}
+
   yargs-parser@18.1.3:
     dependencies:
       camelcase: 5.3.1
diff --git a/website/docs/ai.md b/website/docs/ai.md
new file mode 100644
index 00000000..3cd50003
--- /dev/null
+++ b/website/docs/ai.md
@@ -0,0 +1,13 @@
+# 在 AI 中使用
+
+ICE PKG 遵循 [llmstxt.org](https://llmstxt.org/) 标准，提供两个文件帮助 AI 工具理解项目文档：
+
+| 文件          | 链接                               | 描述                                                   |
+| ------------- | ---------------------------------- | ------------------------------------------------------ |
+| llms.txt      | https://pkg.ice.work/llms.txt      | 包含所有文档页面的标题、链接和简要描述的结构化索引文件 |
+| llms-full.txt | https://pkg.ice.work/llms-full.txt | 将每个文档页面的完整内容合并到单个文件中               |
+
+## 如何选择
+
+- **llms.txt**：体积较小，消耗 token 少，适合 AI 按需获取特定页面内容的场景
+- **llms-full.txt**：包含完整文档内容，适合需要 AI 全面理解 ICE PKG 的场景，但会消耗更多 token，最适合支持大上下文窗口的 AI 工具
diff --git a/website/docs/cli.md b/website/docs/cli.md
new file mode 100644
index 00000000..cd7e5e4b
--- /dev/null
+++ b/website/docs/cli.md
@@ -0,0 +1,31 @@
+# CLI
+
+## start
+
+启动本地调试服务，监听文件变更并自动重新编译。配置文件变更时会自动重启。
+
+```bash
+$ ice-pkg start [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |
+|    `--port <port>`    | `number`  | 覆盖预览服务端口号            |
+|    `--host <host>`    | `string`  | 覆盖预览服务 host             |
+
+## build
+
+执行编译或打包构建，输出构建产物。
+
+```bash
+$ ice-pkg build [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |
diff --git a/website/docs/config/alias.md b/website/docs/config/alias.md
new file mode 100644
index 00000000..fdd3ed5f
--- /dev/null
+++ b/website/docs/config/alias.md
@@ -0,0 +1,20 @@
+# alias
+
+- 类型：`Record<string, string>`
+- 默认值：`{}`
+
+配置路径别名。
+
+比如，将 `@` 指向 `./src` 目录：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  alias: {
+    '@': './src',
+  },
+});
+```
+
+然后代码里 `import '@/foo'` 会被改成 `import '/path/to/your/project/foo'`。
diff --git a/website/docs/config/bundle.md b/website/docs/config/bundle.md
new file mode 100644
index 00000000..90811f46
--- /dev/null
+++ b/website/docs/config/bundle.md
@@ -0,0 +1,239 @@
+# bundle
+
+该字段定义 [Bundle 模式](../guide/build-modes#bundle-模式) 下额外的配置，若开启，默认生成 `dist` 文件目录。
+
+## formats
+
+:::tip
+推荐使用 [`pkgs`](./pkgs) 替代 `formats` 来配置多产物输出，`pkgs` 提供更灵活的差异化配置能力。
+:::
+
+- 类型：`['esm', 'umd', 'cjs', 'es2017']`
+- 默认值：`['esm', 'es2017']`
+
+输出的类型，默认是输出 `esm` 和 `es2017` 产物。
+
+```shell title=root/dist
+- index.esm.es5.production.js        # 输出 ES module + es5 产物
+- index.esm.es2017.production.js     # 输出 ES module + es2017 产物
+```
+
+若只需要产出 umd 规范产物，可配置为：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    formats: ['umd', 'es2017'],
+  },
+});
+```
+
+则输出以下产物：
+
+```shell title=root/dist
+- index.umd.es5.production.js        # 输出 umd + es5 产物
+- index.umd.es2017.production.js     # 输出 umd + es2017 产物
+```
+
+注意，如果需要打包生成 umd 规范产物，不能够配置多个 entry（入口），否则会报错 `Error: Invalid value "umd" for option "output.format" - UMD and IIFE output formats are not supported for code-splitting builds.`
+
+cjs 规范产物同理将 `formats` 配置为 `['cjs', 'es2017']` 即可。
+
+:::tip
+Bundle 模式的 formats 如果单独配置 `['es2017']` 将不会生效，因为其仅决定产物语法层面规范，而无法决定产物的模块规范。因此其必须与 `'esm'`、`'umd'` 和 `'cjs'` 中的至少一项搭配配置才能正常生成对应模块规范的 ES2017 产物。
+:::
+
+## modes
+
+- 类型：`Array<'development' | 'production'>`
+- 默认值：`['production']`
+
+指定输出的产物是否经过压缩。默认情况下输出的产物是压缩过的。
+
+```shell title="root/dist"
+- index.esm.es5.production.js        # 输出 ES module + es5 产物
+- index.esm.es2017.production.js     # 输出 ES module + es2017 产物
+```
+
+增加 `'development'` 时，会额外输出一份**未压缩的**的产物，这也意味着用户可以在开发态使用该产物获得更多的开发时信息。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    modes: ['production', 'development'],
+  },
+});
+```
+
+```shell title="root/dist"
+- index.esm.es5.development.js        # 输出未压缩产物（ES module + es5）
+- index.esm.es5.production.js         # 输出压缩产物 (ES module + es5)
+- index.esm.es2017.development.js     # 输出未压缩产物 （ES module + es2017）
+- index.esm.es2017.production.js      # 输出压缩产物 (ES module + es2017)
+```
+
+## name
+
+- 类型：`string`
+- 默认值：`package.name`
+
+library 导出的名称，可以通过 `window[name]` 访问，一般配合打包 `umd` 产物时使用。默认值为 `package.json` 配置的 `name` 字段。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    name: 'ICEPKG',
+  },
+});
+```
+
+## externals
+
+- 类型：`boolean | Record<string, string> | (string | RegExp | Record<string, string>)[]`
+- 默认值：`false`
+
+默认情况下，bundle 的产物包含所有依赖产物。该选项可修改这一结果。
+
+若想要 Bundle 不包含依赖产物，可以传入 `true`，其会解析 `package.json` 并将所有依赖 external 掉，包括 node 的依赖。适合针对 Node 环境的构建。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    externals: true,
+  },
+});
+```
+
+若想要自定义配置 externals，则可以直接传入想要 external 的依赖，支持字符串和正则表达式。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    externals: ['react', 'react-dom', /^@ice($|\/)/],
+  },
+});
+```
+
+如果你选择构建 umd 格式，默认情况下会根据一定的规则生成从全局对象上获取依赖的名字，如果你想自定义，则可以直接传入一个对象来配置。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    externals: {
+      react: 'React',
+      'react-dom': 'ReactDOM',
+    },
+  },
+});
+```
+
+## minify
+
+- 类型：`boolean | { js?: boolean | ((mode: string, command: string) => boolean | { options?: swc.JsMinifyOptions }); css?: boolean | ((mode: string, command: string) => boolean | { options?: cssnano.Options });}`
+- 默认值：build 阶段且 mode 是 `production` 时为 `true`，否则为 `false`
+
+是否压缩 JS 和 CSS 资源。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    // production 产物和 development 产物不压缩
+    minify: false,
+    // 修改 JS 和 CSS 压缩参数
+    minify: {
+      js: (mode, command) => ({
+        options: {
+          /* */
+        },
+      }),
+      css: (mode, command) => ({
+        options: {
+          /* */
+        },
+      }),
+    },
+  },
+});
+```
+
+## polyfill
+
+- 类型：`false | 'entry' | 'usage'`
+- 默认值：`false`
+
+配置处理 polyfill 的逻辑。不同值的含义：
+
+- `false`: 不引入任何 polyfill
+- `'entry'`: 根据配置的 format 值在每个文件开头都引入对应的 polyfill
+- `'usage'`: 根据源码中使用到的代码按需引入 polyfill
+
+## compileDependencies
+
+- 类型：`boolean | RegExp[] | string[]`
+- 默认值：`false`
+
+配置是否编译 node_modules 中的依赖。如果值为 `true`，则 node_modules 中的依赖都会编译；如果值为 false 则都不编译；如果值为数组，则只会编译对应的依赖。
+
+```js title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    compileDependencies: ['antd'],
+  },
+});
+```
+
+## browser
+
+- 类型: `boolean`
+- 默认值: `false`
+
+配置解析 Node 模块的时候，是否优先读取 package.json 中的 `browser` 字段。如果你的模块**只运行**在浏览器端，可以开启此选项只 bundle 浏览器相关的代码。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    browser: true,
+  },
+});
+```
+
+## codeSplitting
+
+- 类型：`boolean`
+- 默认值：`true`
+
+是否开启代码分割。Bundle 模式默认启用，会将 `node_modules` 中的公共依赖提取到 `vendor` chunk，多入口之间的共享模块也会被提取。
+
+若关闭代码分割，所有模块将合并输出为单一文件，适合对产物结构有严格要求的场景（如 UMD 发布）：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    codeSplitting: false,
+  },
+});
+```
+
+:::tip
+UMD 格式由于 Rollup 限制，已默认启用 `inlineDynamicImports`，分包设置对 UMD 产物不生效。
+:::
diff --git a/website/docs/config/declaration.md b/website/docs/config/declaration.md
new file mode 100644
index 00000000..cf55c2cf
--- /dev/null
+++ b/website/docs/config/declaration.md
@@ -0,0 +1,75 @@
+# declaration
+
+- 类型：`boolean | { outputMode?: 'multi' | 'unique'; generator?: 'tsc' | 'oxc' }`
+- 默认值：`true`
+
+配置 `.d.ts` 类型文件的生成行为。默认会为 TypeScript 文件自动生成类型文件。
+
+## outputMode
+
+- 类型：`'multi' | 'unique'`
+- 默认值：`'multi'`
+
+控制类型文件的输出位置：
+
+- `'multi'`：将 `.d.ts` 文件输出到每个 Transform 产物目录下（如 `esm/`、`es2017/`）
+- `'unique'`：将所有 `.d.ts` 文件统一输出到根目录的 `typings/` 文件夹
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    outputMode: 'unique',
+  },
+});
+```
+
+## generator
+
+- 类型：`'tsc' | 'oxc'`
+- 默认值：`'tsc'`
+
+选择生成类型文件的工具：
+
+- `'tsc'`：使用 TypeScript 官方编译器生成类型文件
+- `'oxc'`：使用 [oxc-transform](https://oxc.rs/) 生成 isolated declaration，速度更快，但要求源码符合 [isolated declarations](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html) 规范
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    generator: 'oxc',
+  },
+});
+```
+
+## allowJs
+
+- 类型：`boolean`
+- 默认值：`false`
+
+是否为 JavaScript 文件生成类型文件。当项目使用 [JSDoc](https://jsdoc.app/) 为 JavaScript 添加了类型注解时，开启此选项可以生成对应的 `.d.ts` 文件。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    allowJs: true,
+  },
+});
+```
+
+## 禁用类型生成
+
+若不需要生成类型文件，可将其设置为 `false`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: false,
+});
+```
diff --git a/website/docs/config/define.md b/website/docs/config/define.md
new file mode 100644
index 00000000..ce44a852
--- /dev/null
+++ b/website/docs/config/define.md
@@ -0,0 +1,45 @@
+# define
+
+- 类型：`Record<string, string | boolean | number | object | null>`
+- 默认值：`{ __DEV__: 'true' | 'false', 'process.env.NODE_ENV': '"development"' | '"production"', 'import.meta.vitest': 'undefined' }`
+
+定义编译时环境变量，会在编译时被替换。注意：属性值会经过一次 `JSON.stringify()` 转换。
+
+例如，希望在代码中注入版本号，用全局变量 `__VERSION__` 来替代：
+
+```ts title="build.config.mts"
+import pkg from './package.json' assert { type: 'json' };
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  define: {
+    __VERSION__: pkg.version,
+  },
+});
+```
+
+在编译时，所有 `__VERSION__` 都会被替换为项目的版本号。
+
+:::tip
+
+在 TS 项目中，需要在 `typings.d.ts` 或其他类型声明文件中，声明 `define` 所设置的属性，以便通过类型检查，并获得类型提示。比如：
+
+```ts title=typings.d.ts
+declare const __VERSION__: string;
+```
+
+:::
+
+ICE PKG 默认注入了 `__DEV__` 全局变量，用于标识开发态环境。这个变量在输出一些仅在 development 环境的信息时非常有用。比如，输出在用户开发态才显示的警告信息。
+
+```ts title=index.ts
+if (__DEV__) {
+  console.warn('请注意，这可能会产生错误！');
+}
+```
+
+:::info 发生了什么？
+实际上，在编译时，`__DEV__` 会被替换为 `process.env.NODE_ENV !== 'production'`。
+:::
+
+另外，ICE PKG 默认会将 `import.meta.vitest` 替换为 `undefined`。这意味着在源码里使用 Vitest 的 [in-source test](https://vitest.dev/guide/in-source.html) 写法时，非测试构建默认不会把对应测试逻辑保留到产物中。
diff --git a/website/docs/config/entry.md b/website/docs/config/entry.md
new file mode 100644
index 00000000..6c7b44c8
--- /dev/null
+++ b/website/docs/config/entry.md
@@ -0,0 +1,32 @@
+# entry
+
+- 类型：`string | string[] | { [entryAlias: string]: string }`
+- 默认值：`'./src/index'`
+
+指定构建入口。支持配置单入口或者多个入口。
+
+指定单个入口：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  entry: './src/index',
+});
+```
+
+指定多个入口：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  // 数组形式
+  entry: ['./src/foo', './src/bar'],
+  // 对象形式，key 值作为 chunk name
+  entry: {
+    foo: './src/foo',
+    bar2: './src/bar',
+  },
+});
+```
diff --git a/website/docs/config/helpers.md b/website/docs/config/helpers.md
new file mode 100644
index 00000000..094ff95f
--- /dev/null
+++ b/website/docs/config/helpers.md
@@ -0,0 +1,34 @@
+# helpers
+
+- 类型：`'external' | 'inline'`
+- 默认值：`'external'`
+
+配置 SWC 编译时辅助函数（helper functions）的处理方式。
+
+- **`'external'`（默认）**：从 `@swc/helpers` 包中导入 helper 函数，产物体积更小，但需要消费方的运行环境中存在该依赖。
+- **`'inline'`**：将 helper 函数内联到每个文件中，无需外部依赖，适合对外发布的独立类库。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  helpers: 'inline',
+});
+```
+
+也可以在 [`pkgs`](./pkgs) 中为某个产物单独配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017' },
+    {
+      module: 'umd',
+      bundle: true,
+      helpers: 'inline', // 仅 UMD 产物内联 helpers
+    },
+  ],
+});
+```
diff --git a/website/docs/config/index.md b/website/docs/config/index.md
new file mode 100644
index 00000000..be00c19d
--- /dev/null
+++ b/website/docs/config/index.md
@@ -0,0 +1,38 @@
+# 构建配置
+
+## 配置文件
+
+若希望对 ICE PKG 的能力进行配置，推荐在项目根目录中添加名为 `build.config.mts` 的配置文件：
+
+```ts title=build.config.mts
+import { defineConfig } from '@ice/pkg';
+
+// 使用 defineConfig 工具函数以获得更好的类型提示
+export default defineConfig({
+  // 配置选项
+});
+```
+
+注：ICE PKG 支持的配置文件类型包括：
+
+- `build.config.mts`
+- `build.config.mjs`
+- `build.config.ts`
+- `build.config.js`
+
+## 配置项总览
+
+| 配置项                       | 说明                    |
+| ---------------------------- | ----------------------- |
+| [entry](./entry)             | 构建入口                |
+| [alias](./alias)             | 路径别名                |
+| [define](./define)           | 编译时环境变量          |
+| [sourceMaps](./source-maps)  | 是否生成 sourcemap      |
+| [jsxRuntime](./jsx-runtime)  | JSX 转换方式            |
+| [plugins](./plugins)         | 插件配置                |
+| [helpers](./helpers)         | SWC helper 函数处理方式 |
+| [server](./server)           | 内置预览服务器配置      |
+| [declaration](./declaration) | 类型文件生成配置        |
+| [transform](./transform)     | Transform 模式配置      |
+| [bundle](./bundle)           | Bundle 模式配置         |
+| [pkgs](./pkgs)               | 多构建单元配置          |
diff --git a/website/docs/config/jsx-runtime.md b/website/docs/config/jsx-runtime.md
new file mode 100644
index 00000000..adf974c5
--- /dev/null
+++ b/website/docs/config/jsx-runtime.md
@@ -0,0 +1,36 @@
+# jsxRuntime
+
+- 类型：`'automatic' | 'classic'`
+- 默认值：`'automatic'`
+
+设置 [JSX 转换](https://reactjs.org/blog/2020/09/22/introducing-the-new-jsx-transform.html)的方式，并交给编译工具（SWC）编译处理 JSX 语法。
+
+假设有这样一段 JSX 代码：
+
+```jsx
+import React from 'react';
+
+function App() {
+  return <h1>Hello World</h1>;
+}
+```
+
+当 `jsxRuntime` 的值是 `automatic`，编译结果是：
+
+```js
+import { jsx as _jsx } from 'react/jsx-runtime';
+
+function App() {
+  return _jsx('h1', { children: 'Hello world' });
+}
+```
+
+当 `jsxRuntime` 的值是 `classic`，编译结果是：
+
+```js
+import React from 'react';
+
+function App() {
+  return React.createElement('h1', null, 'Hello world');
+}
+```
diff --git a/website/docs/config/pkgs.md b/website/docs/config/pkgs.md
new file mode 100644
index 00000000..acf93d57
--- /dev/null
+++ b/website/docs/config/pkgs.md
@@ -0,0 +1,125 @@
+# pkgs
+
+`@ice/pkg` 2.0 引用的新式配置方式
+
+- 类型：`Array<PresetPkg | PkgUserConfig | boolean | undefined>`
+- 默认值：`undefined`
+
+配置多个构建单元（package），每个 pkg 可以独立控制构建模式、格式、入口、输出目录等。适用于需要同时输出多种格式或多个子包的场景。
+
+## PresetPkg（预设格式）
+
+最简单的用法是直接传入预设格式字符串，快速开启对应产物：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: ['esm', 'cjs', '!umd'],
+});
+```
+
+支持的预设值：
+
+- Transform 格式（直接字符串）：`'esm'`、`'cjs'`、`'es2017'`
+- Bundle 格式（以 `!` 为前缀）：`'!esm'`、`'!cjs'`、`'!es2017'`、`'!umd'`、`'!mf'`
+
+## PkgUserConfig 配置项
+
+### id
+
+- 类型：`string`
+
+当前 pkg 的唯一标识，可在其他 pkg 的 `extends` 中引用。
+
+### module
+
+- 类型：`'esm' | 'cjs' | 'umd' | 'mf'`
+- 默认值：`'esm'`
+
+产物的模块规范：
+
+- `'esm'`：输出 ES Module 格式，使用 `import/export` 语法，对 Tree-Shaking 友好，适合被打包工具消费的组件库或工具库
+- `'cjs'`：输出 CommonJS 格式，使用 `require/module.exports`，兼容所有版本的 Node.js，适合 Node 模块
+- `'umd'`：输出 UMD 格式，同时兼容 ESM、CJS 和浏览器全局变量，适合需要通过 `<script>` 直接引入的前端类库，需配合 `bundle: true` 使用
+- `'mf'`：输出 Module Federation 格式，用于跨应用共享模块，需配合 `bundle: true` 及相关插件使用，详见 [Module Federation](../guide/mf)
+
+### target
+
+- 类型：`'es5' | 'es2017' | 'es2022'`
+- 默认值：`'es5'`
+
+产物的 JavaScript 语法目标版本，决定编译器会将哪些语法降级处理：
+
+- `'es5'`：将所有现代语法（箭头函数、class、async/await 等）编译为 ES5，兼容性最好，但产物体积最大，适合需要兼容旧版浏览器的场景
+- `'es2017'`：保留 async/await、箭头函数、class、解构等大部分现代语法，不做降级，可运行在市场份额 > 95% 的现代浏览器上，产物体积更小。详见 [ES2017 产物](../guide/build#es2017-产物)
+- `'es2022'`：保留更多新语法（如顶层 await、class 私有字段等），产物体积最小，仅适合运行环境明确支持 ES2022 的场景
+
+### bundle
+
+- 类型：`boolean`
+- 默认值：`false`
+
+是否使用 Bundle 模式构建。`false` 为 Transform 模式（逐文件编译），`true` 为 Bundle 模式（打包）。
+
+### outputDir
+
+- 类型：`string`
+
+指定该 pkg 的产物输出目录，覆盖默认目录。
+
+### entryRoot
+
+- 类型：`string`
+
+Transform 模式下输出路径的相对根目录，优先级高于全局 [`transform.entryRoot`](./transform#entryroot)。
+
+### extends
+
+- 类型：`Array<PresetPkg | string>`
+
+继承其他 pkg 的配置，值为 PresetPkg 字符串或其他 pkg 的 `id`。注意，不能引入循环，否则会报错
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { id: 'base', module: 'esm', entry: './src/index.ts' },
+    { extends: ['base'], module: 'cjs', outputDir: 'cjs' },
+  ],
+});
+```
+
+### plugins
+
+- 类型：`Array`
+
+仅对当前 pkg 生效的插件，不影响其他 pkg。与全局 [`plugins`](./plugins) 用法相同。
+
+### disable
+
+- 类型：`boolean`
+
+禁用该 pkg，构建时跳过。可以在不改动配置的情况下，通过环境变量或者其他变量进行控制。
+
+---
+
+以下配置项含义与对应的顶层或 bundle 配置相同，在 pkg 中配置时会按优先级覆盖全局配置，仅作用于当前 pkg：
+
+| 配置项                | 同                                                         | 说明                  |
+| --------------------- | ---------------------------------------------------------- | --------------------- |
+| `entry`               | [entry](./entry)                                           | 构建入口              |
+| `alias`               | [alias](./alias)                                           | 路径别名              |
+| `define`              | [define](./define)                                         | 编译时环境变量        |
+| `sourceMaps`          | [sourceMaps](./source-maps)                                | 是否生成 sourcemap    |
+| `jsxRuntime`          | [jsxRuntime](./jsx-runtime)                                | JSX 转换方式          |
+| `declaration`         | [declaration](./declaration)                               | 类型文件生成配置      |
+| `helpers`             | [helpers](./helpers)                                       | SWC helper 处理方式   |
+| `externals`           | [bundle.externals](./bundle#externals)                     | 外部依赖              |
+| `name`                | [bundle.name](./bundle#name)                               | UMD 导出名称          |
+| `compileDependencies` | [bundle.compileDependencies](./bundle#compiledependencies) | 是否编译 node_modules |
+| `polyfill`            | [bundle.polyfill](./bundle#polyfill)                       | polyfill 处理方式     |
+| `minify`              | [bundle.minify](./bundle#minify)                           | 是否压缩产物          |
+| `engine`              | [engine](../guide/engine)                                  | 构建引擎（实验性）    |
+| `codeSplitting`       | `boolean`，默认 `true`                                     | 是否开启代码分割      |
diff --git a/website/docs/config/plugins.md b/website/docs/config/plugins.md
new file mode 100644
index 00000000..667ee3dc
--- /dev/null
+++ b/website/docs/config/plugins.md
@@ -0,0 +1,21 @@
+# plugins
+
+- 类型：`Array<string | [string, any?]>`
+- 默认值：`[]`
+
+ICE PKG 基于 [build-scripts](https://github.com/ice-lab/build-scripts) 插件系统，配置额外的 ICE PKG 插件，以进行更深度的工程定制。更多内容请参考[插件开发](../plugin/development)。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    // npm 依赖
+    '@ice/plugin-docusaurus',
+    // 相对路径
+    './customPlugin.mjs',
+    // 指定插件选项
+    ['@ice/plugin-docusaurus', { title: 'Hello World' }],
+  ],
+});
+```
diff --git a/website/docs/config/server.md b/website/docs/config/server.md
new file mode 100644
index 00000000..3f5b4067
--- /dev/null
+++ b/website/docs/config/server.md
@@ -0,0 +1,144 @@
+# server
+
+- 类型：`boolean | ServerUserConfig`
+- 默认值：`false`
+
+配置内置预览服务器。设为 `true` 时使用默认配置启动服务器；设为对象时可进行详细配置。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: true,
+});
+```
+
+## port
+
+- 类型：`number`
+- 默认值：`5138`
+
+指定服务器监听的端口号。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+});
+```
+
+## host
+
+- 类型：`string`
+- 默认值：`'0.0.0.0'`
+
+指定服务器监听的 host。
+
+## https
+
+- 类型：`HttpsServerOptions | SecureServerSessionOptions`
+- 默认值：`undefined`
+
+启用 HTTPS 服务器。配置后 HTTP 服务器将被禁用。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+import fs from 'node:fs';
+
+export default defineConfig({
+  server: {
+    https: {
+      key: fs.readFileSync('./ssl/key.pem'),
+      cert: fs.readFileSync('./ssl/cert.pem'),
+    },
+  },
+});
+```
+
+## headers
+
+- 类型：`Record<string, string | string[]>`
+- 默认值：`undefined`
+
+为所有响应添加自定义 HTTP 响应头。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: {
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+    },
+  },
+});
+```
+
+## cors
+
+- 类型：`boolean | CorsOptions`
+- 默认值：`undefined`
+
+配置跨域（CORS）策略：
+
+- `true`：使用默认选项启用 CORS（允许所有来源，不推荐用于生产环境）
+- `false`：禁用 CORS
+- 对象：使用 [cors](https://github.com/expressjs/cors) 的详细选项
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: {
+    cors: {
+      origin: 'https://your-site.com',
+    },
+  },
+});
+```
+
+## proxy
+
+- 类型：`Record<string, string | HttpProxyMiddlewareOptions> | HttpProxyMiddlewareOptions[]`
+- 默认值：`undefined`
+
+配置请求代理规则，将指定路径的请求转发到其他服务。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: {
+    proxy: {
+      '/api': 'http://localhost:4000',
+    },
+  },
+});
+```
+
+## publicDir
+
+- 类型：`string | { name?: string } | Array<string | { name?: string }>`
+- 默认值：`{ name: 'public' }`
+
+配置静态文件目录，目录下的文件会在服务器启动后直接提供访问。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: {
+    publicDir: 'static',
+  },
+});
+```
+
+## autoServeBundle
+
+- 类型：`boolean`
+- 默认值：`true`
+
+是否自动将构建产物（Bundle）通过服务器提供访问。
diff --git a/website/docs/config/source-maps.md b/website/docs/config/source-maps.md
new file mode 100644
index 00000000..8b43df0f
--- /dev/null
+++ b/website/docs/config/source-maps.md
@@ -0,0 +1,24 @@
+# sourceMaps
+
+- 类型：`boolean | 'inline'`
+- 默认值：start 阶段默认为 `true`，build 阶段默认为 `false`
+
+是否生成 sourcemap，这在代码调试的时候非常有用。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  sourceMaps: true,
+});
+```
+
+这会为所有产物额外输出 `.js.map` 文件。如果你想要 sourcemap 是内联在源码中的，可将选项配置为 `inline`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  sourceMaps: 'inline',
+});
+```
diff --git a/website/docs/config/transform.md b/website/docs/config/transform.md
new file mode 100644
index 00000000..cf50ca03
--- /dev/null
+++ b/website/docs/config/transform.md
@@ -0,0 +1,115 @@
+# transform
+
+:::tip
+Transform 模式是 ICE PKG 默认的编译模式。
+:::
+
+该字段定义 [Transform 模式](../guide/build-modes#transform-模式) 下额外的配置。默认配置是：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    formats: ['esm', 'es2017'],
+  },
+});
+```
+
+## formats
+
+:::tip
+推荐使用 [`pkgs`](./pkgs) 替代 `formats` 来配置多产物输出，`pkgs` 提供更灵活的差异化配置能力。
+:::
+
+- 类型：`Array<'cjs' | 'esm' | 'es2017'>`
+- 默认值：`['esm', 'es2017']`
+
+输出的类型。ICE PKG 会默认把产物输出到 `esm` (输出 ES module + ES5 产物) 和 `es2017` (输出 ES module + ES2017 产物) 两个文件夹。
+
+```shell
+- esm    # ES module + ES5 产物
+- es2017 # ES module + ES2017 产物
+```
+
+若想要输出 CommonJS 产物，可如下配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    formats: ['cjs', 'esm', 'es2017'],
+  },
+});
+```
+
+则输出如下文件夹：
+
+```shell
+- cjs    # CommonJS + ES5 产物
+- esm    # ES module + ES5 产物
+- es2017 # ES module + ES2017 产物
+```
+
+## entryRoot
+
+- 类型：`string`
+- 默认值：自动推导（已配置 entry 父目录的最近公共祖先）
+
+用于控制 Transform 模式输出路径的相对根目录。该配置只影响产物路径映射，不影响文件处理范围。
+
+例如，当 entry 是 `./src/a/b/c/index.ts`：
+
+- `entryRoot: './src/a/b'` 时，输出为 `esm/c/index.js`
+- `entryRoot: './src'` 时，输出为 `esm/a/b/c/index.js`
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  entry: './src/a/b/c/index.ts',
+  transform: {
+    formats: ['esm'],
+    entryRoot: './src/a/b',
+  },
+});
+```
+
+当使用 `pkgs` 配置时，`pkgs[].entryRoot` 的优先级高于 `transform.entryRoot`。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    entryRoot: './src',
+  },
+  pkgs: [
+    {
+      id: 'button',
+      entry: './src/components/button/index.ts',
+      entryRoot: './src/components',
+    },
+  ],
+});
+```
+
+## excludes
+
+- 类型：`string | string[]`
+- 默认值：`['**/__tests__/**']`
+
+排除无需编译的文件。默认会排除 `__tests__` 目录下文件。比如，我们还不想编译 `src` 下以 `*.test.[j|t]s` 结尾的测试文件。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    excludes: ['**/__tests__/**', '*.test.[j|t]s'],
+  },
+});
+```
+
+`excludes` 的配置完全遵循 [minimatch](https://github.com/isaacs/minimatch) 写法。
diff --git a/website/docs/guide/build-modes.md b/website/docs/guide/build-modes.md
new file mode 100644
index 00000000..fa9903a1
--- /dev/null
+++ b/website/docs/guide/build-modes.md
@@ -0,0 +1,211 @@
+# 构建模式
+
+ICE PKG 原生提供 **Transform** 和 **Bundle** 两种构建模式，你可以根据实际的开发需求选择对应的构建模式。
+
+## 模式对比
+
+| 对比项       | Transform 模式        | Bundle 模式            |
+| ------------ | --------------------- | ---------------------- |
+| 构建方式     | 逐文件编译            | 以入口为起点，递归打包 |
+| 产物结构     | 与源码目录一一对应    | 合并为少数几个文件     |
+| Tree-Shaking | 友好，由使用方负责    | 依赖构建工具内部处理   |
+| 外部依赖处理 | 不处理，保留 import   | 可选打包或 external    |
+| 适用场景     | React 组件、Node 模块 | 前端类库、UMD 格式产物 |
+
+## 如何选择
+
+- 开发 **React 组件、Rax 组件、Node 模块**等，推荐使用 **Transform 模式**，产物调试性好，且对 Tree-Shaking 友好
+- 开发**前端类库**，或需要输出 **UMD 格式**、在浏览器中直接引入的场景，推荐使用 **Bundle 模式**
+
+## Transform 模式
+
+Transform 模式即把源文件**逐个编译**到输出目录，不对依赖做任何处理。
+
+### 工作原理
+
+假设有以下的文件结构：
+
+```md
+src
+├── components
+│ ├── About.jsx
+│ └── Button.tsx
+├── index.ts
+├── util.js
+└── index.scss
+```
+
+经过 ICE PKG 构建后，得到以下的结果：
+
+```md
+esm
+├── components
+│ ├── About.js
+│ ├── Button.d.ts
+│ └── Button.js
+├── index.d.ts
+├── index.js
+├── util.js
+└── index.scss
+```
+
+可以看到，在 Transform 模式下，ICE PKG 对源文件的处理是：
+
+- 对于 TypeScript 文件（`.ts`/`.tsx`），将会被编译成 JavaScript 文件，并输出对应的 `.d.ts` 类型文件
+- 对于 JSX 文件（`.jsx`），将会被编译成 JavaScript 文件，但不会生成 `.d.ts`（因为没有类型信息）
+- 对于 JavaScript 文件，将会进行语法编译
+- 其他类型的文件（比如 `.css`、`.scss` 等等），不做任何编译操作，将会被直接拷贝到输出目录
+
+### 输入目录
+
+Transform 模式的**处理范围**由 `entry` 决定：每个 entry 文件所在目录及其子目录中的文件都会被处理，且各 entry 之间互不重叠。
+
+**单个 entry**（默认）：`entry` 默认为 `./src/index`，因此 `./src` 目录下的所有文件都会被处理：
+
+```
+src/               ← 处理范围
+├── components/
+│   └── Button.tsx
+├── utils/
+│   └── format.ts
+└── index.ts       ← entry
+```
+
+**多个 entry**：每个 entry 对应一个独立的处理范围，互不干扰。
+
+```ts title="build.config.mts"
+export default defineConfig({
+  entry: ['./src/browser/index.ts', './src/node/index.ts'],
+});
+```
+
+```
+src/
+├── browser/       ← 处理范围（来自第一个 entry）
+│   ├── index.ts
+│   └── polyfill.ts
+└── node/          ← 处理范围（来自第二个 entry）
+    ├── index.ts
+    └── fs.ts
+```
+
+两个目录的文件相互独立，不会混入对方的产物中。
+
+### 输出目录
+
+输出分为两层：**顶层目录**和**目录内的文件路径**。
+
+**顶层目录**由产物格式决定：
+
+- 使用 `transform.formats` 时，默认以格式名作为目录名，如 `esm`、`es2017`、`cjs`
+- 使用 `pkgs` 时，以 `outputDir` 为准；未配置 `outputDir` 时，以 `id` 为准；未配置 `id` 时，自动根据 `module` 和 `target` 推导：
+  - 优先使用 `module` 名（如 `esm`、`cjs`），与 `transform.formats` 的目录结构保持一致
+  - 若 `module` 名已被同一 `pkgs` 中其他 pkg 占用，则改用 `module-target`（如 `esm-es2017`）
+
+**目录内的文件路径**由 `entryRoot` 控制：以 `entryRoot` 为根，将源文件的相对路径映射到输出目录中。`entryRoot` 默认为所有 entry 所在目录的**最近公共祖先目录**（自动推导）。
+
+以下面的 entry 配置为例：
+
+```ts title="build.config.mts"
+export default defineConfig({
+  entry: ['./src/a/index.ts', './src/b/index.ts'],
+});
+```
+
+两个 entry 的最近公共祖先是 `./src`，`entryRoot` 默认为 `./src`，输出结构如下：
+
+```
+esm/
+├── a/
+│   └── index.js
+└── b/
+    └── index.js
+```
+
+**自定义 entryRoot**：可通过 `transform.entryRoot` 手动指定，从而控制文件在输出目录内的路径深度。例如 entry 为 `./src/a/b/c/index.ts` 时：
+
+- `entryRoot: './src/a/b'` → 输出 `esm/c/index.js`
+- `entryRoot: './src'` → 输出 `esm/a/b/c/index.js`
+
+注意，`entryRoot` 必须是所有 entry 目录的公共祖先，否则会报错。使用 `pkgs` 时，可在单个 pkg 上配置 `entryRoot`，优先级高于全局 `transform.entryRoot`。
+
+## Bundle 模式
+
+Bundle 模式即以入口文件作为起点，**递归处理各种模块**，最终把相同类型的文件合并成一个构建产物。
+
+### 工作原理
+
+假设有以下的文件结构：
+
+```
+src
+├── components
+│   └── Button.tsx
+├── index.tsx
+└── index.scss
+```
+
+经过 ICE PKG 构建后，得到以下的构建结果，所有的输出都默认输出到 `dist/` 目录下，可以通过 `outputDir` 自定义输出位置：
+
+```
+dist
+├── index.esm.es2017.production.js
+└── index.esm.es2017.production.css
+```
+
+### 分包规则
+
+Bundle 模式默认开启代码分割（`codeSplitting: true`），分包策略如下：
+
+- **`node_modules` 中的依赖**：统一提取到 `vendor` chunk，避免重复打包
+- **多入口共享模块**：被多个入口同时引用的模块也会提取到 `vendor` chunk
+- **UMD 格式**：不支持代码分割，所有模块合并为单一文件输出，同时会内联全部的动态 import 语法。
+
+例如，多入口场景下产物结构可能如下：
+
+```
+dist/
+├── foo.esm.es2017.production.js   ← 入口 foo 的产物
+├── bar.esm.es2017.production.js   ← 入口 bar 的产物
+└── vendor.esm.es2017.production.js ← foo 和 bar 共享的模块
+```
+
+如需关闭代码分割，可配置 `codeSplitting: false`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    codeSplitting: false,
+  },
+});
+```
+
+### 外部依赖（external）
+
+默认情况下，Bundle 模式会将所有依赖打包进产物。如果你希望某些依赖由使用方提供（如 `react`），可以配置 `external`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    externals: {
+      react: 'React',
+      'react-dom': 'ReactDOM',
+    },
+  },
+});
+```
+
+:::caution
+字符串形式的 external 只做**精确匹配**，不会自动匹配子路径。例如配置 `externals: ['react']` 只会 external `react`，不会 external `react/jsx-runtime`、`react/server` 等子路径导入，这些仍会被打包进产物。
+
+如需同时 external 包及其所有子路径，可以使用正则表达式，此时将无法正确匹配到 UMD Name，通常用于 Node 模块的构建：
+
+```ts
+externals: ['react', /^react\//];
+```
+
+:::
diff --git a/website/docs/guide/build.md b/website/docs/guide/build.md
index d6ba6cd3..03fa9505 100644
--- a/website/docs/guide/build.md
+++ b/website/docs/guide/build.md
@@ -1,31 +1,145 @@
 # 构建产物
 
-本文讲述不同[构建模式](./abilities#双模式构建)下的产物说明以及适用的场景。完整的产物构建配置可查看文档 [Transform 模式构建配置](../reference/config#transform)和 [Bundle 模式构建配置](../reference/config#bundle)。
-
+本文讲述不同[构建模式](./build-modes)下的产物说明以及适用的场景。完整的产物构建配置可查看文档 [Transform 模式构建配置](../config/transform)和 [Bundle 模式构建配置](../config/bundle)。
 
 ## 构建产物说明
 
-ICE PKG 默认支持 `esm`、`es2017`、`cjs`、`umd` 四种构建产物类型。每种产物类型在不同构建模式下支持情况、模块规范、语法规范说明如下表：
+ICE PKG 默认支持 `esm`、`es2017`、`cjs`、`umd`、`mf` 五种构建产物类型。每种产物类型在不同构建模式下支持情况、模块规范、语法规范说明如下表：
 
-| 产物类型 | Transform 模式 | Bundle 模式 | 模块规范  | 语法规范 |
-| :------: | :------------: | :---------: | :-------: | :------: |
-|   `esm`    |     ✅支持      |    ✅支持    | ES Module |   ES5    |
-|  `es2017`  |     ✅支持      |    ✅支持    | ES Module |  ES2017  |
-|   `cjs`    |     ✅支持      |    ✅支持    | CommonJS  |   ES5    |
-|   `umd`    |    ❌不支持     |    ✅支持    |    UMD    |   ES5    |
+| 产物类型 | Transform 模式 | Bundle 模式 |     模块规范      | 语法规范 |
+| :------: | :------------: | :---------: | :---------------: | :------: |
+|  `esm`   |     ✅支持     |   ✅支持    |     ES Module     |   ES5    |
+| `es2017` |     ✅支持     |   ✅支持    |     ES Module     |  ES2017  |
+|  `cjs`   |     ✅支持     |   ✅支持    |     CommonJS      |   ES5    |
+|  `umd`   |    ❌不支持    |   ✅支持    |        UMD        |   ES5    |
+|   `mf`   |    ❌不支持    |   ✅支持    | Module Federation |    —     |
 
 每种构建产物的优缺点和适用场景如下表所示：
 
-| 产物类型 | 优点 | 缺点 | 适用场景 |
-| :-------: | ---- | ---- | --------- |
-|   `esm`    | 兼容性较好 | 体积大 | 消费产物的应用打包时不编译 `node_modules`；或者运行环境支持的 ECMAScript 版本较低 |
-| `es2017` | 保留大部分 JavaScript 语法，体积小 | 兼容性差 | 消费产物的应用打包时编译 `node_modules`；或者运行环境支持的 ES2017 语法。更多说明可参考[文档](./abilities#es2017-产物) |
-| `cjs` | 兼容各版本的 Node.js | 体积大 | 在 Node.js 环境下运行 |
-| `umd` | 兼容运行在浏览器和 Node.js 中 | 体积大 | 用户的项目中某个依赖 external，需要在 HTML 中通过 `<script />` 引入 UMD 产物；或者在浏览器中直接使用产物 |
+| 产物类型 | 优点                               | 缺点     | 适用场景                                                                                                           |
+| :------: | ---------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------ |
+|  `esm`   | 兼容性较好                         | 体积大   | 消费产物的应用打包时不编译 `node_modules`；或者运行环境支持的 ECMAScript 版本较低                                  |
+| `es2017` | 保留大部分 JavaScript 语法，体积小 | 兼容性差 | 消费产物的应用打包时编译 `node_modules`；或者运行环境支持的 ES2017 语法。更多说明可参考[文档](./build#es2017-产物) |
+|  `cjs`   | 兼容各版本的 Node.js               | 体积大   | 在 Node.js 环境下运行                                                                                              |
+|  `umd`   | 兼容运行在浏览器和 Node.js 中      | 体积大   | 用户的项目中某个依赖 external，需要在 HTML 中通过 `<script />` 引入 UMD 产物；或者在浏览器中直接使用产物           |
 
-## 默认构建产物
+## 配置产物输出
 
-下面是 ICE PKG 默认的产物构建配置：
+推荐使用 `pkgs` 配置多个构建单元，每个 pkg 独立控制模块格式、语法目标、入口、输出目录等。
+
+**基础用法**：直接传入预设字符串，快速输出对应格式产物。字符串前缀 `!` 表示使用 Bundle 模式构建，不带 `!` 则使用 Transform 模式：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  // esm → Transform 模式 esm+es5 产物
+  // es2017 → Transform 模式 esm+es2017 产物
+  // cjs → Transform 模式 cjs+es5 产物
+  // !umd → Bundle 模式 umd 产物（! 前缀表示 Bundle 模式）
+  pkgs: ['esm', 'es2017', 'cjs', '!umd'],
+});
+```
+
+**完整配置**：通过对象形式精确控制每个产物的输出：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017', outputDir: 'es2017' },
+    { module: 'esm', target: 'es5', outputDir: 'esm' },
+    { module: 'cjs', target: 'es5', outputDir: 'cjs' },
+  ],
+});
+```
+
+**差异化配置**：不同产物使用不同的入口或配置，互不干扰：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    // browser 端产物，入口不同，需要 external react
+    {
+      id: 'browser',
+      module: 'esm',
+      target: 'es2017',
+      entry: './src/index.browser.ts',
+      externals: { react: 'React' },
+    },
+    // node 端产物，CJS 格式
+    {
+      id: 'node',
+      module: 'cjs',
+      target: 'es2017',
+      entry: './src/index.node.ts',
+    },
+  ],
+});
+```
+
+**通过 `extends` 复用配置**：抽取公共配置，避免重复：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    // 定义基础配置
+    {
+      id: 'base',
+      module: 'esm',
+      target: 'es2017',
+      externals: { react: 'React', 'react-dom': 'ReactDOM' },
+    },
+    // 继承 base，只覆盖 outputDir
+    { extends: ['base'], outputDir: 'es2017' },
+    // 继承 base，修改 target
+    { extends: ['base'], target: 'es5', outputDir: 'esm' },
+  ],
+});
+```
+
+**动态禁用某个产物**：通过 `disable` 结合环境变量按需开关某个 pkg：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017' },
+    // 仅在需要时构建 UMD 产物
+    { bundle: true, module: 'umd', disable: !process.env.BUILD_UMD },
+  ],
+});
+```
+
+**为某个产物单独添加插件**：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017' },
+    {
+      module: 'esm',
+      target: 'es5',
+      // 仅对此 pkg 生效的插件
+      plugins: ['./my-legacy-plugin.mjs'],
+    },
+  ],
+});
+```
+
+完整配置项说明请参考 [pkgs 配置项](../config/pkgs)。
+
+### 兼容模式
+
+对于从 v1 迁移的项目，也可以通过 `transform.formats` 或 `bundle.formats` 指定输出格式：
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
@@ -34,51 +148,75 @@ export default defineConfig({
   transform: {
     formats: ['esm', 'es2017'],
   },
-})
+  bundle: {
+    formats: ['umd'],
+  },
+});
 ```
 
-默认情况下，ICE PKG 只启用 Transform 模式并将产物分别输出到 `esm` 目录和 `es2017` 目录。
+:::caution
+`pkgs` 一旦配置，`transform.formats` 和 `bundle.formats` 将**自动失效**，产物完全由 `pkgs` 接管。两种方式不能混用。
+:::
+
+## 默认构建产物
+
+下面是 ICE PKG 默认的产物构建配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [{ module: 'esm', target: 'es2017' }],
+});
+```
 
 执行 `npm run build` 命令后，得到以下的构建产物：
+
 ```md
 ── es2017
-|  ├── index.d.ts
-|  └── index.js
-├── esm
-|  ├── index.d.ts
-|  └── index.js
+| ├── index.d.ts
+| └── index.js
 ```
 
 输出构建目录名和构建产物类型一一对应。
 
 对于 React 组件来说，它们会在应用中消费，而应用通常是会被打包工具打包后才能在生产环境中使用。以 Webpack 举例，可以配置 `resolve.conditionNames = ['es2017', 'esm']`，这样会优先使用 es2017 产物，配合在 `browserslist` 中配置高版本的浏览器（比如中后台场景），打包出来的产物能直接运行在目标浏览器，体积也会更小。
 
-## 构建现代产物
+## ES2017 产物
+
+ICE PKG 支持额外输出 ES2017 规范的 [Modern 产物](https://web.dev/publish-modern-javascript/)。这份产物在编译时会保留大部分的 JavaScript 语法特性（Class、箭头函数、async/await、解构、spread 运算符等），可以运行在[大部分的现代浏览器版本](https://caniuse.com/async-functions,object-values,object-entries,mdn-javascript_builtins_object_getownpropertydescriptors,pad-start-end,mdn-javascript_grammar_trailing_commas_trailing_commas_in_functions)上（市场份额 > 95%）。当网站不再转译这些语法时，文件的字节数得以大幅减少，从而极大地改善脚本加载性能。
 
-如果你确定你的运行环境支持 [ES2017 产物](./abilities#es2017-产物)，推荐使用以下的配置仅生成体积更小的构建产物：
+以一个简单的 React 组件为例，ES2017 产物与 ES5 产物的大小对比：
+
+| 产物        | 大小 |
+| ----------- | ---- |
+| ES2017 产物 | 1.8k |
+| ES5 产物    | 3.7k |
+
+:::tip
+传统的 NPM 包开发中，大量的代码仍被编译到 ES5 语法。若你想计算你的网站在使用 ES2017 产物后可实现的产物大小和性能改进，可以试试 [estimator.dev](https://estimator.dev/) 这个工具。
+:::
+
+如果你确定你的运行环境支持 ES2017，推荐使用以下的配置仅生成体积更小的构建产物：
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  transform: {
-    formats: ['es2017'],
-  },
-  bundle: {
-    formats: ['esm', 'es2017'],
-  },
-})
+  // Transform 模式仅输出 es2017 产物
+  // !es2017 表示 Bundle 模式输出 esm+es2017 产物
+  pkgs: ['es2017', '!es2017'],
+});
 ```
-> [Transform 模式](./abilities#transform-模式)和 [Bundle 模式](./abilities#bundle-模式)均支持生成 ES2017 产物。你可以根据实际的需求，选择启动单个模式或者双模式。
 
 构建产物如下：
 
 ```md
 ── es2017
-|  ├── index.d.ts
-|  └── index.js
+| ├── index.d.ts
+| └── index.js
 ├── dist
-|  └── index.esm.es2017.production.js
+| └── index.esm.es2017.production.js
 ```
 
 ## ES Module 和 CommonJS 产物
@@ -95,36 +233,34 @@ export default defineConfig({
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  transform: {
-    formats: ['cjs', 'es2017'],
-  },
-  bundle: {
-    formats: ['cjs', 'esm', 'es2017'],
-  },
-})
+  // cjs → Transform 模式 cjs+es5 产物
+  // es2017 → Transform 模式 esm+es2017 产物
+  // !cjs → Bundle 模式 cjs+es5 产物
+  // !es2017 → Bundle 模式 esm+es2017 产物
+  pkgs: ['cjs', 'es2017', '!cjs', '!es2017'],
+});
 ```
-> [Transform 模式](./abilities#transform-模式)和 [Bundle 模式](./abilities#bundle-模式) 均支持生成 ES2017 产物和 CommonJS 产物。你可以根据实际的需求，选择启动单个模式或者双模式。
 
 执行 `npm run build` 后输出的产物如下：
 
 ```md
 ── cjs
-|  ├── index.d.ts
-|  └── index.js
+| ├── index.d.ts
+| └── index.js
 ├── es2017
-|  ├── index.d.ts
-|  └── index.js
+| ├── index.d.ts
+| └── index.js
 ├── dist
-|  ├── index.cjs.es5.production.js
-|  └── index.esm.es2017.production.js
+| ├── index.cjs.es5.production.js
+| └── index.esm.es2017.production.js
 ```
 
 其中，`cjs` 目录和 `es2017` 目录是 Transform 构建模式的产物；`dist` 目录是 Bundle 构建模式的产物。
 
-| 产物类型 | 模块规范 | 语法规范 |
-| :-------: | ---- | ---- |
-|   es2017    | ES Module  | ES2017 |
-| cjs | CommonJS | ES5 |
+| 产物类型 | 模块规范  | 语法规范 |
+| :------: | --------- | -------- |
+|  es2017  | ES Module | ES2017   |
+|   cjs    | CommonJS  | ES5      |
 
 然后在 `package.json` 中配置 `exports` 产物导出：
 
@@ -134,7 +270,7 @@ export default defineConfig({
     ".": {
       "import": "./es2017/index.js",
       "require": "./cjs/index.js",
-      "default": "./cjs/index.js",
+      "default": "./cjs/index.js"
     }
   }
 }
@@ -142,19 +278,22 @@ export default defineConfig({
 
 ## UMD 产物
 
-一般情况下，[前端类库](./scenarios#前端类库)的场景需要打包构建生成 UMD 产物。
+一般情况下，[前端类库](./scenario/library)的场景需要打包构建生成 UMD 产物。
 
-ICE PKG 仅支持在 [Bundle 模式](./abilities#bundle-模式)下构建出 UMD 产物，配置方式如下：
+ICE PKG 仅支持在 [Bundle 模式](./build-modes#bundle-模式)下构建出 UMD 产物，配置方式如下：
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  bundle: {
-    formats: ['umd'],
-    name: 'my-library',  // 配置 umd 模块导出的名字，通过 `window[name]` 访问
-  }
-})
+  pkgs: [
+    {
+      bundle: true,
+      module: 'umd',
+      name: 'my-library', // 配置 umd 模块导出的名字，通过 `window[name]` 访问
+    },
+  ],
+});
 ```
 
 执行 `npm run build` 后，将会输出以下的构建结果：
@@ -165,18 +304,23 @@ dist
 └── index.umd.es5.production.js
 ```
 
-如果需要额外输出一份未压缩的 UMD 产物以方便调试构建，可以新增 [bundle.modes 配置项](../reference/config#modes)：
+如果需要额外输出一份未压缩的 UMD 产物以方便调试构建，可以新增 `modes` 配置：
 
-```diff title="build.config.mts"
+```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
+  pkgs: [
+    {
+      bundle: true,
+      module: 'umd',
+      name: 'my-library',
+    },
+  ],
   bundle: {
-    formats: ['umd'],
-    name: 'my-library',
-+   modes: ['production', 'development'],
-  }
-})
+    modes: ['production', 'development'],
+  },
+});
 ```
 
 执行 `npm run build` 后，将会输出以下的构建结果：
@@ -188,3 +332,7 @@ dist
 ├── index.umd.es5.production.css
 └── index.umd.es5.production.js
 ```
+
+## 模块联邦产物
+
+模块联邦（Module Federation）产物用于微前端架构下的跨应用模块共享场景，需配合 [`@ice/pkg-plugin-mf`](./mf) 插件使用，详见[模块联邦指南](./mf)。
diff --git a/website/docs/guide/configure.md b/website/docs/guide/configure.md
new file mode 100644
index 00000000..c26dfbec
--- /dev/null
+++ b/website/docs/guide/configure.md
@@ -0,0 +1,58 @@
+# 配置
+
+## 配置文件
+
+ICE PKG 会自动从项目根目录读取配置文件，支持以下格式（按优先级排序）：
+
+- `build.config.mts`
+- `build.config.mjs`
+- `build.config.ts`
+- `build.config.js`
+
+推荐使用 `build.config.mts`，配合 `defineConfig` 工具函数可以获得完整的类型提示和自动补全：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  // 配置项
+});
+```
+
+## 自定义配置文件路径
+
+如果需要使用非默认路径的配置文件，可以通过 `--config` 参数指定：
+
+```bash
+npx icepkg build --config ./config/build.config.mts
+```
+
+## 导出函数
+
+配置文件也支持导出一个函数：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig(() => ({
+  pkgs: ['esm', 'es2017'],
+}));
+```
+
+## 环境变量
+
+可以结合环境变量动态调整配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    minify: process.env.NODE_ENV === 'production',
+  },
+});
+```
+
+## 完整配置项
+
+所有可用配置项请参考[配置文档](../config/)。
diff --git a/website/docs/guide/css.md b/website/docs/guide/css.md
new file mode 100644
index 00000000..7bf2ca7b
--- /dev/null
+++ b/website/docs/guide/css.md
@@ -0,0 +1,93 @@
+# CSS
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+## 基本用法
+
+比如 `src` 文件夹下存在 `index.tsx` 和 `index.css`，可以直接在 `index.tsx` 引入样式文件。如：
+
+<Tabs>
+
+<TabItem value="index.tsx" label="src/index.tsx">
+
+```tsx
+import * as React from 'react';
+import './a.css';
+
+export default function Home() {
+  return <div className="container"></div>;
+}
+```
+
+</TabItem>
+<TabItem value="index.css" label="src/index.css">
+
+```css
+.container {
+  color: red;
+}
+```
+
+</TabItem>
+</Tabs>
+
+## 预处理器
+
+ICE PKG 内置支持 `.scss`、`.less`、`.sass` 文件，使用方式与 `.css` 文件保持一致。
+
+在开启 Bundle 模式后，需要安装对应的预处理器依赖：
+
+```bash
+# .scss and .sass
+npm add -D sass
+
+# .less
+npm add -D less
+```
+
+## CSS Modules
+
+ICE PKG 也支持 [CSS Modules](https://github.com/css-modules/css-modules)，样式文件需以 `.module.css`、`.module.less` 或 `.module.scss` 结尾。
+
+<Tabs>
+
+<TabItem value="index.tsx" label="src/index.tsx">
+
+```tsx
+import styles from './index.module.css';
+
+export default () => (
+  <div className={styles.root}>
+    <div className={styles.item}>Hello</div>
+  </div>
+);
+```
+
+</TabItem>
+<TabItem value="index.module.css" label="src/index.module.css">
+
+```css
+.root {
+  display: flex;
+}
+.item {
+  color: red;
+}
+```
+
+</TabItem>
+</Tabs>
+
+:::tip
+如果你在组件里直接通过 `import './index.css'` 的方式引入样式，样式将会对全局样式造成影响。最好给该组件内所有的 CSS 选择器增加前缀，比如：
+
+```diff
+- .container {
++ .rc-container {
+  color: red;
+}
+```
+
+或者你可以直接使用 CSS Modules 直接引入样式。
+:::
diff --git a/website/docs/guide/engine.md b/website/docs/guide/engine.md
new file mode 100644
index 00000000..c0ae459a
--- /dev/null
+++ b/website/docs/guide/engine.md
@@ -0,0 +1,96 @@
+# 构建引擎
+
+ICE PKG 的 Bundle 模式支持多种底层构建引擎，可以根据项目需求选择合适的引擎。
+
+:::info
+`engine` 配置项**仅对 Bundle 模式生效**，Transform 模式固定使用 Rollup 编译，不受此配置影响。
+:::
+
+## 引擎类型
+
+| 引擎                                | 说明                                      | 适用场景                     |
+| ----------------------------------- | ----------------------------------------- | ---------------------------- |
+| [`rollup`](https://rollupjs.org/)   | 默认引擎，稳定性好                        | 通用场景，推荐使用           |
+| [`rolldown`](https://rolldown.rs/)  | 实验性引擎，基于 Rust 实现，构建速度更快  | 追求构建速度，接受实验性风险 |
+| [`rslib`](https://lib.rsbuild.dev/) | 基于 Rsbuild/Rspack，主要用于模块联邦场景 | 模块联邦（MF）构建           |
+
+## 配置方式
+
+通过 `bundle.engine` 或 `pkgs` 中的 `engine` 字段配置引擎：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    engine: 'rolldown', // 'rollup' | 'rolldown' | 'rslib'
+  },
+});
+```
+
+使用 `pkgs` 时，可以为每个产物单独指定引擎：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017', engine: 'rolldown' },
+    { module: 'cjs', target: 'es5' }, // 使用默认引擎 rollup
+  ],
+});
+```
+
+## rollup（默认）
+
+[Rollup](https://rollupjs.org/) 是 ICE PKG 的默认 Bundle 引擎，经过充分验证，稳定性好，适合大多数场景。
+
+**注意事项**：
+
+- Transform 模式始终使用 Rollup 编译，`engine` 配置仅对 Bundle 模式生效
+- 支持 `modifyRollupOptions` 钩子来自定义 Rollup 配置
+
+## rolldown（实验性）
+
+[Rolldown](https://rolldown.rs/) 是基于 Rust 实现的高性能打包工具，API 与 Rollup 兼容，构建速度显著提升。
+
+**注意事项**：
+
+- 目前处于实验性阶段，生产环境使用需自行评估风险
+- 部分 Rollup 插件可能存在兼容性问题
+- `modifyRollupOptions` 钩子在 rolldown 引擎下同样生效
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    engine: 'rolldown',
+    formats: ['esm', 'cjs'],
+  },
+});
+```
+
+## rslib
+
+[Rslib](https://lib.rsbuild.dev/) 基于 Rsbuild/Rspack 构建，主要用于**模块联邦（Module Federation）**场景，配合 ICE PKG 的 MF 插件使用。
+
+**注意事项**：
+
+- 直接使用 rslib 引擎通常无需手动配置，MF 插件会自动选择该引擎
+- 支持 `modifyRslibConfig` 钩子来自定义 Rslib 配置
+- CSS 模块、Less、Sass 均已内置支持
+
+更多关于模块联邦的内容，请参考[模块联邦指南](./mf)。
+
+## 各引擎功能对比
+
+| 功能                  | rollup |   rolldown   | rslib |
+| --------------------- | :----: | :----------: | :---: |
+| Transform 模式        |   ✅   |      ❌      |  ❌   |
+| Bundle 模式           |   ✅   |      ✅      |  ✅   |
+| 模块联邦              |   ❌   |      ❌      |  ✅   |
+| 稳定性                |   高   | 中（实验性） |  高   |
+| 构建速度              |  一般  |      快      | 一般  |
+| `modifyRollupOptions` |   ✅   |      ✅      |  ❌   |
+| `modifyRslibConfig`   |   ❌   |      ❌      |  ✅   |
diff --git a/website/docs/guide/jsx-plus.md b/website/docs/guide/jsx-plus.md
index 69ac5770..9a195af1 100644
--- a/website/docs/guide/jsx-plus.md
+++ b/website/docs/guide/jsx-plus.md
@@ -24,10 +24,8 @@ $ npm i @ice/pkg-plugin-jsx-plus --save-dev
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  plugins: [
-    ['@ice/pkg-plugin-jsx-plus'],
-  ],
-})
+  plugins: [['@ice/pkg-plugin-jsx-plus']],
+});
 ```
 
 然后你就可以使用更强大的 JSX+ 语法了：
@@ -68,7 +66,7 @@ function ExampleComponent(props) {
 ```jsx
 {/* Array or Plain Object*/}
 <tag x-for={item in foo}>{item}</tag>
-  
+
 <tag x-for={(item, key) in foo}>{key}: {item}</tag>
 ```
 
@@ -111,9 +109,13 @@ function ExampleComponent(props) {
 
 ```jsx
 <Waterfall
-  renderHeader={() => (<view>header</view>)}
-  renderFooter={() => (<view>footer</view>)}
-  renderItem={(item, index) => (<view>{index}: {item}</view>}
+  renderHeader={() => <view>header</view>}
+  renderFooter={() => <view>footer</view>}
+  renderItem={(item, index) => (
+    <view>
+      {index}: {item}
+    </view>
+  )}
 />
 ```
 
@@ -122,7 +124,9 @@ function ExampleComponent(props) {
 ```jsx
 <Waterfall>
   <view slot="header">header</view>
-  <view slot="item" slot-scope="props">{props.index}: {props.item}</view>
+  <view slot="item" slot-scope="props">
+    {props.index}: {props.item}
+  </view>
   <view slot="footer">footer</view>
 </Waterfall>
 ```
@@ -146,7 +150,7 @@ function ExampleComponent(props) {
 参考实现：
 
 ```jsx
-<div className={classnames({ item: true, active: val})} />
+<div className={classnames({ item: true, active: val })} />
 ```
 
 `classnames` 方法能力参考[同名 npm 包](https://npmjs.com/classnames)。
@@ -166,8 +170,6 @@ function ExampleComponent(props) {
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  plugins: [
-    ['@ice/pkg-plugin-jsx-plus', { moduleName: 'rax' }],
-  ],
-})
+  plugins: [['@ice/pkg-plugin-jsx-plus', { moduleName: 'rax' }]],
+});
 ```
diff --git a/website/docs/guide/mf.md b/website/docs/guide/mf.md
index 163186c0..c1207871 100644
--- a/website/docs/guide/mf.md
+++ b/website/docs/guide/mf.md
@@ -50,7 +50,7 @@ export default defineConfig({
 
 ## Tips
 
-- 如果通过配置 `outputDir` 修改输出目录
+- 如果通过配置 `outputDir` 修改输出目录，需同步更新宿主应用中消费微模块产物的路径
 - 可以通过 `server: true` 开启本地预览服务调试微模块产物
 
 ## 注意事项
diff --git a/website/docs/guide/monorepo.md b/website/docs/guide/monorepo.md
index 96fe9d86..7fac3ca8 100644
--- a/website/docs/guide/monorepo.md
+++ b/website/docs/guide/monorepo.md
@@ -10,7 +10,7 @@ ICE PKG 提供了对 Monorepo 方案的支持。目前支持：
 ICE PKG 的 Monorepo 方案是基于 [pnpm workspace](https://pnpm.io/workspaces) + 包构建器 [`@ice/pkg`](https://www.npmjs.com/package/@ice/pkg)，因此我们需要确保我们的开发环境满足：
 
 - [pnpm](https://pnpm.io/) 版本确保是 7 或以上
-- [node.js](https://nodejs.org) 版本确保是 16 或以上
+- [node.js](https://nodejs.org) 版本确保是 18 或以上，推荐使用 20
 
 ## 创建项目
 
@@ -21,14 +21,15 @@ $ pnpm create @ice/pkg my-monorepo
 ```
 
 选择 React 组件项目类型：
+
 ```bash
 ? 请选择项目类型 (Use arrow keys)
   React 组件
   Node 模块
-  前端类库  
+  前端类库
   Rax 组件
 ❯ Monorepo React 组件
-  Monorepo Node 模块  
+  Monorepo Node 模块
 ```
 
 ## 目录介绍
@@ -36,16 +37,16 @@ $ pnpm create @ice/pkg my-monorepo
 以一个多 React 组件默认脚手架项目为例子：
 
 ```md
-├── build.config.mts       # 文档预览配置文件
+├── build.config.mts # 文档预览配置文件
 ├── package.json
-├── packages               # 存放子项目的目录
-|  ├── component-a
-|  ├── component-b
-|  └── component-c
-├── pages                  # 文档首页
-|  ├── index.module.css
-|  └── index.tsx
-├── pnpm-workspace.yaml    # 定义工作空间的子项目
+├── packages # 存放子项目的目录
+| ├── component-a
+| ├── component-b
+| └── component-c
+├── pages # 文档首页
+| ├── index.module.css
+| └── index.tsx
+├── pnpm-workspace.yaml # 定义工作空间的子项目
 ├── tsconfig.base.json
 └── tsconfig.json
 ```
@@ -65,23 +66,12 @@ $ pnpm create @ice/pkg packages/your-lib --workspace
 ? 请选择项目类型 (Use arrow keys)
 ❯ React 组件
   Node 模块
-  前端类库  
+  前端类库
   Rax 组件
 ```
 
 根据实际的需求选择对应的项目类型，然后填写子项目的 npm 包名后，完成子项目的创建。
 
-然后，我们还需要在根目录的 package.json 中 `devDependencies` 里添加依赖，以能正常启动文档预览服务（详细原因在后面[文档预览](#文档预览)小节中会讲到）：
-
-```diff
-# package.json
-{
-  "devDependencies": {
-+   "@ali/your-lib": "workspace:*"
-  }
-}
-```
-
 ## 本地调试
 
 在项目根目录下执行以下命令进行安装并构建工作区(workspace)的每个子项目：
@@ -89,6 +79,7 @@ $ pnpm create @ice/pkg packages/your-lib --workspace
 ```bash
 $ pnpm install && pnpm packages:build
 ```
+
 这个时候，所有的依赖都安装完成，并且有依赖的子项目之间也自动 link 好了。
 
 我们在项目根目录下执行以下命令启动调试：
@@ -97,132 +88,10 @@ $ pnpm install && pnpm packages:build
 $ pnpm start
 ```
 
-这时会监听每个子项目的代码变更，并启动文档预览服务：
-
-![undefined](https://img.alicdn.com/imgextra/i2/O1CN01UwaC811GIqSgUoo7p_!!6000000000600-2-tps-1126-814.png) 
+这时会监听每个子项目的代码变更，持续构建产物。
 
 这时我们可以修改源码，进行本地调试了。
 
-## 文档预览
-
-文档预览服务基于 [`@ice/pkg-plugin-docusaurus`](./preview) ICE PKG 插件。推荐一个 Monorepo 项目存在一个文档站点服务，并支持预览所有的子项目的文档。
-
-### 添加依赖到根目录的 `package.json`
-
-由于启动文档本地预览调试是在项目的根目录进行，但在子项目的文档中通常直接依赖了子包，在文档进行打包构建的时候会找不到对应的子包，因此需要在项目根目录的 `package.json` 中添加对应的子项目依赖：
-
-```diff
-# package.json
-{
-  "devDependencies": {
-+   "@ali/your-lib": "workspace:*"
-  }
-}
-```
-
-### 子项目文档预览
-
-`packages` 目录下每个子项目都会有一个 `docs` 目录，用来存放该子项目的文档。比如：
-
-```md
-./packages/component-a
-├── README.md
-├── build.config.mts
-├── docs
-|  ├── index.md
-|  ├── usage.md
-|  └── usage.md
-├── package.json
-├── src
-└── tsconfig.json
-```
-
-在项目根目录下执行以下命令，会起一个 docusaurus 的文档预览：
-
-```shell
-$ pnpm docs:start
-```
-
-访问控制台中打印的文档地址就能查看文档了：
-
-![undefined](https://intranetproxy.alipay.com/skylark/lark/0/2023/png/301926/1673436424615-4d7bb212-8072-4a38-a644-21ca2a41fd34.png) 
-
-以  `packages` 目录为根目录，页面的路由默认根据下每个子项目的文件路径自动生成的。比如上面的 `./packages/component-a/docs/index.md`，路由会自动为 `/component-a/docs/`（没有 `packages` 前缀）。
-
-所有的文档选项配置，都在根目录的 `build.config.mts` 文件中配置，下面是推荐的配置：
-
-```ts
-import { defineConfig } from '@ice/pkg';
-
-export default defineConfig({
-  plugins: [
-    [
-      '@ice/pkg-plugin-docusaurus',
-      {
-        path: 'packages',
-        sidebarItemsGenerator: (args: any) => {
-          // The index.md doc should not be the category, so we rewrite the default isCategoryIndex function.
-          function isCategoryIndex({ fileName, directories }: any) {
-            const eligibleDocIndexNames: string[] = [
-              'readme',
-              directories[0].toLowerCase(),
-            ];
-            return eligibleDocIndexNames.includes(fileName.toLowerCase());
-          }
-          const defaultSidebarItems = args.defaultSidebarItemsGenerator({
-            ...args,
-            isCategoryIndex,
-          });
-          // 1. Remove the `docs` category.
-          // 2. Remove category link.
-          const newSidebarItems = defaultSidebarItems.map(({ link, ...rest }: any) => ({
-            ...rest,
-            items: rest.items.map((item: any) => item.items).flat(),
-          }));
-
-          return newSidebarItems;
-        },
-        exclude: ['**/node_modules/**'],
-        onBrokenLinks: 'warn',
-      },
-    ],
-  ],
-});
-```
-
-更多配置说明可参考[文档预览](https://pkg.ice.work/guide/preview)。
-
-### 定制文档首页
-
-默认情况下，当我们访问根路由(`/`)是返回 404 页面的。如果我们想定制文档首页的内容，我们可以增加 [`pageRouteBasePath`](./preview#pageroutebasepath) 配置：
-
-首先在 `build.config.mts` 中新增以下内容：
-```diff
-import { defineConfig } from '@ice/pkg';
-
-export default defineConfig({
-  plugins: [
-    [
-      '@ice/pkg-plugin-docusaurus',
-      {
-+       pageRouteBasePath: '/',
-      },
-    ],
-  ],
-});
-```
-
-然后在根目录下新增 `pages` 目录，然后新增 `index.tsx` 或者` index.md` 文件，此文件将会被渲染到根路由。
-
-```tsx
-// pages/index.tsx
-export default function Home() {
-  return (
-    <div>我是首页</div>
-  )
-}
-```
-
 ## 发布
 
 对于 npm 包进行版本管理和发布，ICE PKG 推荐使用社区的版本控制工具：
diff --git a/website/docs/guide/preview.md b/website/docs/guide/preview.md
index 518d55b5..9083948d 100644
--- a/website/docs/guide/preview.md
+++ b/website/docs/guide/preview.md
@@ -1,8 +1,74 @@
 # 文档预览
 
-开发的组件库之类的项目，需要本地预览效果以及编写文档，可以选择社区中的文档站点开发工具。
+开发组件库时，通常需要本地预览组件效果并编写文档，可以选择社区中的文档站点工具。以下是一些支持 React 组件预览的推荐工具：
 
-例如：
+- [Storybook](https://storybook.js.org/) — 业界最流行的组件开发工具，支持交互式预览和文档编写
+- [Docusaurus](https://docusaurus.io/) — Meta 出品的文档站点框架，支持 MDX，可嵌入 React 组件
+- [Rspress](https://rspress.dev/) — 基于 Rspack 的高性能文档框架，支持 MDX 和 React 组件预览
+- [Dumi](https://d.umijs.org/) — 面向组件库的文档工具，内置组件 Demo 预览能力
 
-- [docusaurus](https://docusaurus.io/)
-- [rspress](https://rspress.org/)
+## 注意事项
+
+文档工具在预览组件时直接运行源码，而非构建产物，因此需要将 `build.config.mts` 中的相关配置同步到文档工具的构建配置中。
+
+### alias
+
+如果配置了路径别名，需要在文档工具的构建配置中同步设置。以 Storybook 为例：
+
+```ts title=".storybook/main.ts"
+import { mergeConfig } from 'vite';
+
+export default {
+  viteFinal: (config) =>
+    mergeConfig(config, {
+      resolve: {
+        alias: {
+          '@': '/src',
+        },
+      },
+    }),
+};
+```
+
+### define
+
+ICE PKG 默认注入了 `__DEV__`、`process.env.NODE_ENV` 等编译时变量，文档工具运行源码时这些变量不会被自动替换，需要显式定义。以 Storybook 为例：
+
+```ts title=".storybook/main.ts"
+import { mergeConfig } from 'vite';
+
+export default {
+  viteFinal: (config) =>
+    mergeConfig(config, {
+      define: {
+        __DEV__: true,
+      },
+    }),
+};
+```
+
+如果你配置了自定义的 `define`，同样需要在文档工具中补充对应的定义。
+
+### jsxRuntime
+
+ICE PKG 默认使用 `automatic` 模式转换 JSX，即自动从 `react/jsx-runtime` 引入转换函数，无需在每个文件中手动 `import React`。大多数文档工具默认也使用 `automatic` 模式，通常无需额外配置。
+
+如果你将 `jsxRuntime` 改为 `classic`，需要在文档工具中同步配置。以 Storybook 为例：
+
+```ts title=".storybook/main.ts"
+import { mergeConfig } from 'vite';
+
+export default {
+  viteFinal: (config) =>
+    mergeConfig(config, {
+      esbuild: {
+        jsxFactory: 'React.createElement',
+        jsxFragment: 'React.Fragment',
+      },
+    }),
+};
+```
+
+---
+
+以上配置方式以 Storybook（基于 Vite）为例，其他工具的具体写法请参考各自的官方文档。
diff --git a/website/docs/guide/scenario/library.md b/website/docs/guide/scenario/library.md
new file mode 100644
index 00000000..2de08d9c
--- /dev/null
+++ b/website/docs/guide/scenario/library.md
@@ -0,0 +1,56 @@
+# 前端类库
+
+前端类库指的是运行在浏览器环境中的 JavaScript 模块，并且所有的依赖都会打包到这个模块里面。
+
+## 适用场景
+
+**场景一：通过 `<script />` 引入 UMD 产物**
+
+类似 [React](https://unpkg.com/browse/react@18.2.0/umd/)、[moment](https://unpkg.com/browse/moment@2.29.4/min/) 等类库，用户的项目中把这些依赖 external 掉，需要在 HTML 中通过 `<script />` 引入 UMD 产物：
+
+```html
+<html>
+  <head>
+    <script src="https://unpkg.com/your-lib-name/dist/index.umd.es5.production.js"></script>
+  </head>
+  <body>
+    <script>
+      console.log(window.YourLibName);
+    </script>
+  </body>
+</html>
+```
+
+**场景二：通过 ES Module 方式加载**
+
+在 `<script />` 标签内通过 `ES Module` 方式加载类库：
+
+```html
+<html>
+  <body>
+    <script type="module">
+      import lib from './index.esm.es2017.production.js';
+    </script>
+  </body>
+</html>
+```
+
+## 构建配置
+
+前端类库通常使用 [Bundle 模式](../build-modes#bundle-模式) 构建，以将所有依赖打包到产物中：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    {
+      bundle: true,
+      module: 'umd',
+      name: 'YourLibName', // 配置 umd 模块导出的名字，通过 `window[name]` 访问
+    },
+  ],
+});
+```
+
+更多 UMD 产物配置请参考 [构建产物 — UMD 产物](../build#umd-产物)。
diff --git a/website/docs/guide/scenario/node.md b/website/docs/guide/scenario/node.md
new file mode 100644
index 00000000..22378254
--- /dev/null
+++ b/website/docs/guide/scenario/node.md
@@ -0,0 +1,40 @@
+# Node 模块
+
+如果现在有相同的工具函数在多个 Node 应用被消费，可以把这些公共的函数抽成一个 npm 包，供多个 Node 应用使用。支持经过 Transform 模式生成 CommonJS 产物和 ES Module 产物。
+
+```ts title="src/index.ts"
+import fs from 'fs';
+
+export function writeLicenseToFileHeader(absFilePath: string) {
+  const newFileContent = '/* LICENSE */' + fs.readFileSync(absFilePath, 'utf-8');
+  fs.writeFileSync(absFilePath, newFileContent);
+}
+```
+
+推荐使用以下配置，同时生成 CJS 和 ESM 产物以兼容不同版本的 Node.js：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: ['cjs', 'es2017'],
+});
+```
+
+然后在 `package.json` 中配置 `exports` 产物导出：
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./es2017/index.js",
+      "require": "./cjs/index.js",
+      "default": "./cjs/index.js"
+    }
+  }
+}
+```
+
+:::tip
+不同版本的 Node.js 支持的 ECMAScript 语法可参考 [Node Green 网站](https://node.green/)。Node 12.20.0 及以上已支持 ES Module 和 ES2017 全部语法。
+:::
diff --git a/website/docs/guide/scenario/react.md b/website/docs/guide/scenario/react.md
new file mode 100644
index 00000000..a0d28ec3
--- /dev/null
+++ b/website/docs/guide/scenario/react.md
@@ -0,0 +1,159 @@
+# React 组件
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+如果你在多个不同的项目中共同使用了一个或多个 React 组件，那么你可以考虑把这些公共的 React 组件抽成一个 npm 包，这样你就可以在不同的项目中复用组件了。
+
+## 单组件
+
+假设一个 npm 包仅导出一个 React 组件，推荐使用以下目录结构和写法：
+
+```md
+src
+├── Header # 子组件 Header
+│ ├── index.css
+│ └── index.tsx
+└── index.tsx
+```
+
+<Tabs>
+<TabItem value="index.tsx" label="index.tsx">
+
+```tsx
+import Header from './Header';
+
+//  通过 export default 方式导出
+export default function Component() {
+  return (
+    <div>
+      <Header />
+      ...
+    </div>
+  );
+}
+```
+
+</TabItem>
+
+<TabItem value="Header/index.tsx" label="Header/index.tsx">
+
+```tsx
+import './index.css';
+
+export default function Header() {
+  return <div>Header</div>;
+}
+```
+
+</TabItem>
+</Tabs>
+
+这样在消费处可以通过 `import Component from 'your-component-name'` 的方式导入组件了。
+
+## 组件库
+
+假如一个 npm 包要导出多个不同的组件（即组件库），推荐使用以下的目录组织结构和写法：
+
+```md
+src
+├── Button
+│ ├── index.css
+│ └── index.tsx
+├── Input
+│ ├── index.css
+│ └── index.tsx
+└── index.ts
+```
+
+<Tabs>
+<TabItem value="index.ts" label="index.ts">
+
+```ts
+export * from './Button';
+export * from './Input';
+```
+
+</TabItem>
+
+<TabItem value="Button/index.tsx" label="Button/index.tsx">
+
+```tsx
+import * as React from 'react';
+
+export function Button() {
+  return <button>example</button>;
+}
+```
+
+</TabItem>
+</Tabs>
+
+`src/index.ts` 作为组件库的入口文件，然后统一导出不同的 React 组件，这样就可以通过 `import { Button, Input } from 'your-component-name';` 导入组件了。
+
+:::tip
+有关样式的说明和写法请参考 [CSS](../css) 文档。
+:::
+
+## JSX 支持
+
+ICE PKG 对 `.jsx` 和 `.tsx` 原生支持，使用 [SWC](https://swc.rs/docs/configuration/swcrc) 编译，无需任何额外配置即可直接使用。
+
+JSX 的转换方式可通过 [`jsxRuntime`](../../config/jsx-runtime) 配置项调整，默认使用 `automatic` 模式（无需手动引入 `React`）。
+
+## 发布配置
+
+### exports
+
+推荐在 `package.json` 中配置 `exports` 字段声明 npm 包的入口：
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./esm/index.js",
+      "require": "./cjs/index.js",
+      "es2017": "./es2017/index.js",
+      "default": "./cjs/index.js"
+    },
+    "./feature": {
+      "import": "./esm/feature.js",
+      "require": "./cjs/feature.js",
+      "es2017": "./es2017/feature.js",
+      "default": "./cjs/feature.js"
+    }
+  }
+}
+```
+
+如果需要兼容较低版本的 Node.js，还需同时配置 `main` 字段：
+
+```json
+{
+  "main": "./cjs/index.js"
+}
+```
+
+:::tip
+`exports` 的优先级高于 `main`，两者可以同时配置以兼容不同环境。更多导出规则可参考 [Node.js 文档](https://nodejs.org/dist/latest-v18.x/docs/api/packages.html#package-entry-points)。
+:::
+
+### sideEffects
+
+`sideEffects` 用于告知打包工具（如 Webpack）当前模块是否有副作用，从而开启更激进的 Tree Shaking。默认值为 `true`。
+
+如果你的组件库代码没有副作用，可以设置为 `false`：
+
+```json
+{
+  "sideEffects": false
+}
+```
+
+如果部分文件（如全局样式）确实有副作用，可以单独列出：
+
+```json
+{
+  "sideEffects": ["*.css", "*.less"]
+}
+```
diff --git a/website/docs/guide/server.md b/website/docs/guide/server.md
new file mode 100644
index 00000000..07f0947a
--- /dev/null
+++ b/website/docs/guide/server.md
@@ -0,0 +1,15 @@
+# 开发服务器
+
+ICE PKG 内置了一个轻量的开发服务器，可在 `start` 模式下直接预览 Bundle 产物，无需额外搭建服务。
+
+通过 [`server`](../config/server) 配置项启用：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  server: true,
+});
+```
+
+启动后访问 `http://localhost:5138` 即可预览产物。支持端口、host、HTTPS、代理、CORS 等配置，详见 [server 配置项](../config/server)。
diff --git a/website/docs/guide/test.md b/website/docs/guide/test.md
index aa4f2836..889193a0 100644
--- a/website/docs/guide/test.md
+++ b/website/docs/guide/test.md
@@ -1,212 +1,83 @@
 # 测试
 
-ICE PKG 不耦合任意一个测试框架，开发者可自由选择 [Jest](https://jestjs.io/) 或 [Vitest](https://vitest.dev/) 开展单元测试。
-
-## 相关链接
-
-- [Jest 官方文档](https://jestjs.io/docs/getting-started)
-- [Vitest 官方文档](https://vitest.dev/guide/)
-- [ts-jest 配置指南](https://kulshekhar.github.io/ts-jest/docs/getting-started/installation)
-- [@swc/jest](https://www.npmjs.com/package/@swc/jest)
-- [Testing Library React](https://testing-library.com/docs/react-testing-library/intro/)
-- [@testing-library/jest-dom](https://github.com/testing-library/jest-dom)
+ICE PKG 不耦合任意一个测试框架，开发者可自由选择 [Jest](https://jestjs.io/) 或 [Vitest](https://vitest.dev/) 以及社区其他框架开展单元测试。
 
 ## Jest
 
-### 安装依赖
+请先参考 [Jest 官方文档](https://jestjs.io/docs/getting-started)完成基础安装和配置。
 
-```bash
-$ npm i jest ts-jest jest-environment-jsdom @testing-library/react @testing-library/jest-dom -D
-```
+### 与 ICE PKG 配置对齐
 
-### 配置
+测试框架直接运行源码，如果 `build.config.mts` 中配置了 `alias` 或 `define`，需要在 Jest 配置中做对应设置。
 
-快速开始时，可以先在项目根目录创建 `jest.config.mjs`：
+**alias**：使用 `moduleNameMapper` 映射路径别名：
 
 ```js title="jest.config.mjs"
 export default {
   preset: 'ts-jest',
   testEnvironment: 'jest-environment-jsdom',
-  setupFilesAfterEnv: ['<rootDir>/jest-setup.ts'],
+  moduleNameMapper: {
+    '^@/(.*)$': '<rootDir>/src/$1',
+  },
 };
 ```
 
-再创建 `jest-setup.ts`：
-
-```ts title="jest-setup.ts"
-import '@testing-library/jest-dom';
-```
-
-并在 `package.json` 中添加脚本：
-
-```diff title="package.json"
-{
-  "scripts": {
-+   "test": "jest"
-  }
-}
-```
-
-如果你希望改用 `@swc/jest` 编译 TS/TSX，可以改成：
+**define**：使用 `globals` 定义编译时变量。ICE PKG 默认注入了 `__DEV__` 等变量，测试时需要显式声明：
 
 ```js title="jest.config.mjs"
 export default {
-  transform: {
-    '^.+\\.(t|j)sx?$': [
-      '@swc/jest',
-      {
-        jsc: {
-          transform: {
-            react: {
-              runtime: 'automatic',
-            },
-          },
-        },
-      },
-    ],
+  preset: 'ts-jest',
+  testEnvironment: 'jest-environment-jsdom',
+  globals: {
+    __DEV__: true,
   },
 };
 ```
 
-### 编写测试用例
-
-#### 非 UI 测试
-
-假设现在要测试 `add()` 函数如下：
-
-```ts title="src/utils/add.ts"
-export default function add(a, b) {
-  return a + b;
-}
-```
-
-新建一个测试用例：
-
-```ts title="tests/add.spec.ts"
-import add from '../src/add';
-
-test('add function', () => {
-  expect(add(1, 2)).toBe(3);
-});
-```
-
-这时，运行 `npm run test` 查看测试结果了。
-
-#### UI 测试
-
-组件 UI 测试推荐使用 [@testing-library/react](https://www.npmjs.com/package/@testing-library/react) 和 [@testing-library/jest-dom](https://www.npmjs.com/package/@testing-library/jest-dom)。上面的快速开始配置已经包含这两个库常用的 jsdom 环境和 matcher 设置。
-
-假设现在要测试一个 Header 组件：
-
-```tsx title="src/components/Header.tsx"
-export default function Header() {
-  return <h2 data-testid="title">Jest Test</h2>;
-}
-```
-
-编写组件的测试用例：
-
-```tsx title="tests/Header.spec.tsx"
-import { render, screen } from '@testing-library/react';
-import Header from '../src/components/Header';
-
-test('test Header component', () => {
-  render(<Header />);
-  expect(screen.getByTestId('title')).toHaveTextContent('Jest Test');
-});
-```
-
-最后，运行 `npm run test` 就可以查看测试结果了。
+如果你在 `build.config.mts` 中配置了自定义的 `define`，同样需要在此处补充对应的定义。
 
 ## Vitest
 
-### 安装依赖
+请先参考 [Vitest 官方文档](https://vitest.dev/guide/)完成基础安装和配置。
 
-```bash
-$ npm i vitest jsdom @testing-library/react @testing-library/jest-dom -D
-```
+### 与 ICE PKG 配置对齐
 
-### 配置
+测试框架直接运行源码，如果 `build.config.mts` 中配置了 `alias` 或 `define`，需要在 Vitest 配置中做对应设置。
 
-快速开始时，可以先在项目根目录创建 `vitest.config.mts`：
+**alias**：使用 `resolve.alias` 映射路径别名：
 
-```js title="vitest.config.mts"
+```ts title="vitest.config.mts"
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
+  resolve: {
+    alias: {
+      '@': new URL('./src', import.meta.url).pathname,
+    },
+  },
   test: {
     environment: 'jsdom',
-    setupFiles: ['./vitest-setup.ts'],
-    globals: true,
   },
 });
 ```
 
-默认情况下，ICE PKG 构建时会将 `import.meta.vitest` 替换为 `undefined`，因此可以直接使用 Vitest 的 in-source test 写法，而不会把测试分支带入最终产物。
-
-再创建 `vitest-setup.ts`：
-
-```ts title="vitest-setup.ts"
-import matchers from '@testing-library/jest-dom/matchers';
-import { expect } from 'vitest';
-
-expect.extend(matchers);
-```
-
-并在 `package.json` 中添加脚本：
-
-```diff title="package.json"
-{
-  "scripts": {
-+   "test": "vitest"
-  }
-}
-```
-
-可直接传入 [vitest 配置](https://vitest.dev/config/)。
-
-以修改 `include` 参数为例：
+**define**：使用 `define` 定义编译时变量。ICE PKG 默认注入了 `__DEV__` 等变量，测试时需要显式声明：
 
-```diff title="vitest.config.mts"
+```ts title="vitest.config.mts"
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
-+ test: {
-+   environment: 'jsdom',
-+   setupFiles: ['./vitest-setup.ts'],
-+   globals: true,
-+   include: ['**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}'],
-+ },
+  define: {
+    __DEV__: true,
+  },
+  test: {
+    environment: 'jsdom',
+  },
 });
 ```
 
-### 编写测试用例
-
-#### 非 UI 测试
-
-请见 [Jest 非 UI 测试章节](#非-ui-测试)。
-
-组件 UI 测试时，上面的快速开始配置已经包含 jsdom 环境、全局 API 和 matcher 扩展。
-
-假设现在测试一个 Header 组件：
-
-```tsx title="src/components/Header.tsx"
-export default function Header() {
-  return <h2 data-testid="title">Vitest Test</h2>;
-}
-```
-
-编写组件的测试用例：
+如果你在 `build.config.mts` 中配置了自定义的 `define`，同样需要在此处补充对应的定义。
 
-```tsx title="tests/Header.spec.tsx"
-import { test, expect } from 'vitest';
-import { render, screen } from '@testing-library/react';
-import Header from '../src/components/Header';
-
-test('test Header component', () => {
-  render(<Header />);
-  expect(screen.getByTestId('title')).toHaveTextContent('Vitest Test');
-});
-```
+### In-source Test
 
-最后，运行 `npm run test` 就可以查看测试结果了。
+ICE PKG 构建时会将 `import.meta.vitest` 替换为 `undefined`，因此可以直接使用 Vitest 的 [in-source test](https://vitest.dev/guide/in-source.html) 写法，测试逻辑不会被带入最终产物。
diff --git a/website/docs/guide/typescript.md b/website/docs/guide/typescript.md
new file mode 100644
index 00000000..9693e629
--- /dev/null
+++ b/website/docs/guide/typescript.md
@@ -0,0 +1,121 @@
+# TypeScript
+
+ICE PKG 原生支持引入和使用 `.ts`/`.tsx` 文件。使用 [SWC](https://swc.rs/docs/configuration/swcrc) 进行编译，相比 `tsc` 有着数十倍的编译速度提升，同时热更新的时间也有明显的减少。
+
+## 类型声明
+
+默认情况下，我们使用的一些模块（比如 `.module.css`、`.jpg` 等）或者全局变量（比如 `NODE_ENV` 等）类型是未定义的，在编辑器中是有报错提示。为此 ICE PKG 默认提供一份类型声明，你可以在项目中新增一个 `d.ts` 类型声明文件并加入以下的内容：
+
+```ts title="src/typings.d.ts"
+/// <reference types="@ice/pkg/types" />
+```
+
+## 声明文件
+
+ICE PKG 默认会为 Transform 模式下的 TypeScript 文件自动生成 `.d.ts` 类型声明文件，并将其输出到每个 Transform 产物目录下（如 `esm/`、`es2017/`）：
+
+```
+esm/
+├── index.d.ts
+└── index.js
+es2017/
+├── index.d.ts
+└── index.js
+```
+
+### 选择生成器
+
+通过 `declaration.generator` 可以选择生成类型文件所使用的工具：
+
+**tsc（默认）**：使用 TypeScript 官方编译器，兼容性最好，支持所有 TypeScript 语法。
+
+**oxc（实验性）**：使用 [oxc-transform](https://oxc.rs/) 生成 isolated declaration，速度比 tsc 快很多。但有以下限制：
+
+- 源码必须符合 [isolated declarations](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-5.html) 规范，即每个导出的类型必须可以独立推断，不依赖跨文件的类型推导
+- 需要在 `tsconfig.json` 中开启 `isolatedDeclarations: true`
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    generator: 'oxc',
+  },
+});
+```
+
+### 控制输出位置
+
+通过 `declaration.outputMode` 可以控制类型文件的输出位置：
+
+- **`multi`（默认）**：将 `.d.ts` 文件输出到每个 Transform 产物目录下
+- **`unique`**：将所有 `.d.ts` 文件统一输出到根目录的 `typings/` 文件夹，适合只需要一份类型文件的场景
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    outputMode: 'unique',
+  },
+});
+```
+
+使用 `unique` 模式时，需要在 `package.json` 中通过 `types` 字段指向类型文件：
+
+```json
+{
+  "types": "./typings/index.d.ts"
+}
+```
+
+### 为 JS 文件生成类型
+
+对于使用 [JSDoc](https://jsdoc.app/) 为 JavaScript 添加了类型注解的项目，可以通过 `declaration.allowJs` 开启对 JS 文件的类型生成：
+
+```js
+/**
+ * @param {number} a
+ * @param {number} b
+ * @returns {number}
+ */
+export function add(a, b) {
+  return a + b;
+}
+```
+
+为 JavaScript 文件开启 [`declaration.allowJs`](../config/declaration#allowjs) 配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: {
+    allowJs: true,
+  },
+});
+```
+
+则会生成一个 `add.d.ts` 文件，内容如下：
+
+```ts
+export function add(a: number, b: number): number;
+```
+
+:::warning 谨慎使用该配置
+若贸然为没有使用 JSDoc 注解的 JavaScript 代码开启该配置，可能会出现自动类型推断错误的情况。
+:::
+
+### 禁用类型生成
+
+若不需要生成类型文件，可将 `declaration` 设置为 `false`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  declaration: false,
+});
+```
+
+完整配置说明请参考 [declaration 配置项](../config/declaration)。
diff --git a/website/docs/index.md b/website/docs/index.md
index a226a6ca..725f3dc8 100644
--- a/website/docs/index.md
+++ b/website/docs/index.md
@@ -1,51 +1,28 @@
-# ICE PKG
+# 简介
 
-ICE PKG 是飞冰开源的 NPM 包开发解决方案，默认支持 React 组件、Rax 组件、Node 模块、前端类库等多场景 NPM 包的研发。
+ICE PKG 是飞冰开源的 NPM 包开发解决方案，默认支持 React 组件、Node 模块、前端类库等多场景 NPM 包的研发。
 
 ## 特性
 
-- **📈 更快**：使用 [SWC](https://swc.rs/docs/configuration/swcrc) 编译和压缩，提升数十倍编译速度
+- **📈 更快**：支持使用 [SWC](https://swc.rs/docs/configuration/swcrc)/[Rolldown](https://rolldown.rs/) 编译和压缩，提升数十倍编译速度
 - **🎊 双模式**：同时提供 Transform + Bundle 两种构建模式
 - **🅾️ 零配置**：无需任何配置，提供内建的 TypeScript、JSX 等构建支持
 - **☄️ 面向未来**：提供 ES2017 产物，打包出面向现代浏览器支持的产物
-- **☘️ 文档预览**：基于 [Docusaurus](https://docusaurus.io/) 提供预览文档、生成静态文档能力
+- **🖥️ 内置开发服务器**：提供内置 Dev Server，开箱即用，无需额外配置
+- **📦 模块联邦支持**：支持 Module Federation（MF），便于跨应用共享模块
+- **🏗️ 多产物构建**：支持同时构建多种格式产物（ESM、CJS、UMD 等），一次命令输出所有目标格式
 
-### 更快
+## 为什么需要 ICE PKG
 
-使用 SWC 与 [tsc](https://www.typescriptlang.org/)、[Babel](https://babeljs.io/) 编译同一个项目之间耗时对比：
+在开发组件库或工具库时，开发者不仅需要专注于实现项目逻辑，还需要处理与代码本身无关的繁琐工作，例如构建、调试、文档预览和测试。社区中虽然有许多工具可以解决其中部分问题，但开发者往往需要同时协调多个工具，面临配置繁琐、生态割裂等困境。
 
-<figure style={{
-  maxWidth: '800px',
-  fontSize: '13px',
-  lineHeight: '20px'
-}}>
-  <img src="https://img.alicdn.com/imgextra/i1/O1CN01MoY2ji23DGjyTw2Dh_!!6000000007221-2-tps-2972-638.png" alt="benchmark" />
+ICE PKG 提供了一套面向 NPM 包研发的一体化解决方案，重点解决以下问题：
 
-<figcaption>Above: benchmark 使用 <a href="https://github.com/maoxiaoke/pkg-benchmark">飞冰 fusion pro</a> 模板</figcaption>
-</figure>
-
-### 双模式
-
-社区的众多方案如 [Microbundle](https://github.com/developit/microbundle)、[tsup](https://github.com/egoist/tsup) 均只支持打包模式 (将所有依赖文件打包成一个文件输出，下称 Bundle 模式)。但 Bundle 模式[并非总是最佳选择](https://github.com/ice-lab/icepkg/issues/301)。其中最为**显著的问题**在于：**对 Tree-Shaking 不友好**，无用的依赖总是会被打包到最终的输出产物中，继而影响应用的体积。
-
-ICE PKG 除支持 Bundle 模式外，也默认支持了 Transform 模式（将文件挨个编译到输出目录）。更多内容请参考[构建能力 — 双模式构建](./guide/abilities#双模式构建)。
-
-### ES2017 产物
-
-为现代浏览器提供 ES2017 产物，可以减少产物体积，亦可加快执行速度。更多内容参考 [构建能力 — es2017 产物](./guide/abilities#es2017-产物)。
-
-### 多场景
-
-依赖 ICE PKG 强大的[双模式](#双模式)能力，支持多类场景的开发需求。包括但不限定于以下场景：
-
-+ React 组件
-+ Rax 组件
-+ Node 模块
-+ 前端类库
-
-### 文档预览
-
-结合 [Docusaurus](https://docusaurus.io/)，ICE PKG 升级了文档预览的能力。更多内容参考 [指南 - 文档预览](./guide/preview)。
+- **构建模式单一**：社区大多数工具仅支持 Bundle 模式，对 Tree-Shaking 不友好，导致最终产物体积虚高。ICE PKG 默认支持 Transform 和 Bundle 双模式，开发者可按需选择最合适的构建方式。
+- **配置成本高**：从零搭建一个支持 TypeScript、JSX、多格式产物输出的构建流程往往需要大量配置。ICE PKG 做到真正零配置开箱即用，内建对 TypeScript、JSX、CSS 等的支持。
+- **构建性能瓶颈**：传统基于 Babel/tsc 的构建工具在大型项目中速度较慢。ICE PKG 集成高性能的 SWC 编译器，构建速度提升数十倍，并支持实验性的 Rolldown 引擎进一步加速。
+- **研发链路割裂**：构建、文档预览、测试等环节往往依赖不同的独立工具。ICE PKG 将这些能力整合到统一的工具链中，降低研发链路的维护成本。
+- **生态协同成本高**：在飞冰（ICE）体系下开发组件或工具包时，往往需要额外适配工程配置。ICE PKG 作为飞冰生态的官方 NPM 包研发方案，与 [ice.js](https://v3.ice.work/) 等工具无缝衔接，真正做到生态内开箱即用。
 
 ## 社区
 
diff --git a/website/docs/migration/v1-to-v2.md b/website/docs/migration/v1-to-v2.md
new file mode 100644
index 00000000..8f689e14
--- /dev/null
+++ b/website/docs/migration/v1-to-v2.md
@@ -0,0 +1,145 @@
+# V1 迁移到 V2
+
+本文档帮助你从 ICE PKG V1 迁移到 V2 版本，列出所有不兼容的变更及对应的迁移方式。
+
+## 升级依赖
+
+```bash
+pnpm add @ice/pkg@latest
+```
+
+---
+
+## Breaking Changes
+
+### 移除 `development` 配置项
+
+`bundle.development` 已移除，请改用 `bundle.modes`：
+
+```diff
+export default defineConfig({
+  bundle: {
+-   development: true,
++   modes: ['development', 'production'],
+  },
+});
+```
+
+---
+
+### `polyfill` 默认值从 `'usage'` 改为 `false`
+
+V1 中 `polyfill` 默认值为 `'usage'`，会自动注入 `core-js` polyfill。V2 中默认值改为 `false`，不再自动注入。
+
+如果你的产物需要 polyfill，请显式配置：
+
+```ts
+export default defineConfig({
+  bundle: {
+    polyfill: 'usage', // 或 'entry'
+  },
+});
+```
+
+---
+
+### `externals` 字符串不再匹配子路径
+
+V1 中配置字符串 `externals` 会模糊匹配子路径（如 `'lodash'` 会同时 external 掉 `lodash/get`）。V2 改为精确匹配，字符串只匹配完整包名。
+
+如需 external 子路径，请改用正则或数组形式：
+
+```ts
+export default defineConfig({
+  bundle: {
+    // V1: externals: { lodash: 'lodash' }  // 会匹配 lodash 及所有子路径
+    // V2: 只匹配 'lodash'，不匹配 'lodash/get'
+    externals: [/^lodash/], // 使用正则匹配所有 lodash 子路径
+  },
+});
+```
+
+---
+
+### 移除 `defineJestConfig` / `defineVitestConfig`
+
+V1 中 `@ice/pkg` 导出了 `defineJestConfig` 和 `defineVitestConfig` 帮助函数，用于将构建配置中的 `alias`、`define` 等同步到测试框架。V2 已移除这两个方法。
+
+请直接在测试框架配置中手动配置 alias 等选项：
+
+```ts
+// vitest.config.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    alias: {
+      '@': './src',
+    },
+  },
+});
+```
+
+同时，V2 支持 [Vitest In-Source Testing](https://vitest.dev/guide/in-source)，`import.meta.vitest` 会在构建产物中被自动替换为 `undefined`，无需额外配置。
+
+---
+
+### UMD 产物默认启用 `inlineDynamicImports`
+
+V2 中 UMD 构建模式下默认启用 `inlineDynamicImports`，所有动态导入会被内联到单个产物文件中。这是为了避免 UMD 产物因分包导致运行时无法加载依赖 chunk 的问题。
+
+如果你之前依赖 UMD 产物的分包行为，需要注意产物结构会发生变化。
+
+---
+
+### ES5 构建模式下默认编译所有依赖
+
+V2 中 Bundle 模式使用 `es5` 语法目标时，会默认对 `node_modules` 中的依赖代码一并编译降级，确保产物语法兼容性。V1 中依赖代码默认不会被编译。
+
+如果你的依赖已经是 ES5，这不会有影响；若依赖包含高版本语法，V2 会自动处理，无需额外配置。
+
+---
+
+### `generateTypesForJs` 迁移到 `declaration.allowJs`
+
+顶级配置项 `generateTypesForJs` 已移除，改为 `declaration.allowJs`：
+
+```diff
+export default defineConfig({
+- generateTypesForJs: true,
++ declaration: {
++   allowJs: true,
++ },
+});
+```
+
+---
+
+## AI 迁移 Prompt
+
+如果你使用支持 Agent 模式的 AI 工具（如 Claude Code、Cursor、Copilot Workspace 等），可以使用以下模板让 AI 自动完成迁移：
+
+```
+你是一个专业的前端工程师，请帮我将当前项目的 ICE PKG 构建配置从 V1 迁移到 V2。
+
+## 任务
+
+1. 读取项目根目录下的 `build.config.mts`（或 `build.config.ts` / `build.config.mjs`）
+2. 检查并修复以下所有 Breaking Changes
+3. 如有涉及测试框架配置（`jest.config.*` / `vitest.config.*`），一并读取并修复
+4. 直接修改文件，完成后输出变更摘要
+
+## Breaking Changes 检查清单
+
+- [ ] `bundle.development: true` → 替换为 `bundle.modes: ['development', 'production']`
+- [ ] `bundle.polyfill` 未配置但原本依赖默认注入 → 根据需要显式设为 `'usage'` 或 `'entry'`
+- [ ] `externals` 使用字符串且需要匹配子路径 → 改用正则，例如 `'lodash'` → `/^lodash/`
+- [ ] 从 `@ice/pkg` 导入了 `defineJestConfig` 或 `defineVitestConfig` → 移除，手动配置测试框架的 alias 等选项
+- [ ] `generateTypesForJs: true` → `declaration: { allowJs: true }`
+
+## 注意事项
+
+- 只修改需要变更的部分，保持其他配置不变
+- 如果某项 Breaking Change 在当前项目中不涉及，跳过即可
+- 修改前先读取文件，确认当前内容后再做变更
+```
diff --git a/website/docs/plugin/development.md b/website/docs/plugin/development.md
new file mode 100644
index 00000000..b4c02bd9
--- /dev/null
+++ b/website/docs/plugin/development.md
@@ -0,0 +1,629 @@
+# 开发插件
+
+ICE PKG 基于 [build-scripts](https://github.com/ice-lab/build-scripts) 插件系统。通过 build-scripts 插件，可以极大地扩展 ICE PKG 的能力。
+
+## 插件示例
+
+### 本地插件
+
+假设在项目根目录下有一个自定义插件 my-plugin：
+
+```js title="plugin.mjs"
+/**
+ * @type {import('@ice/pkg').Plugin}
+ */
+const plugin = (api, options) => {
+  console.log('api: ', api);
+};
+
+export default plugin;
+```
+
+然后在 `build.config.mts` 中引入插件：
+
+```diff
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
++ plugins: [
++   './plugin.mjs',
++ ],
+});
+```
+
+### 发布插件到 npm
+
+推荐插件目录是：
+
+```md
+my-plugin
+├── package.json
+├── tsconfig.json
+├── src
+| └── index.ts // 插件入口
+```
+
+```ts src/index.ts
+import type { Plugin } from '@ice/pkg';
+
+const plugin: Plugin = (api) => {};
+
+export default plugin;
+```
+
+对插件代码进行编译后，在 package.json 中指定插件的入口：
+
+```json
+{
+  "name": "my-plugin",
+  "main": "./esm/index.js",
+  "exports": {
+    // ...
+  }
+}
+```
+
+把插件发布到 npm 后，需要把插件添加到 `build.config.mts` 构建配置中：
+
+```diff
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig(() => ({
+  plugins: [
++   'my-plugin',
+  ],
+}));
+```
+
+## 插件 API
+
+### context
+
+`context` 包含构建时的上下文信息：
+
+- `command`：当前运行命令，start/build/test
+- `commandArgs`：script 命令执行时接受到的参数
+- `rootDir`：项目根目录
+- `userConfig`：用户在构建配置文件 build.config.mts 中配置的内容
+- `pkg`：项目 package.json 中的内容
+
+```js
+const plugin = (api) => {
+  console.log(api.context);
+};
+```
+
+### pluginScope
+
+`pluginScope` 标识当前插件的运行范围，可用于区分插件是在全局还是在某个 pkg 的上下文中被调用：
+
+- `'global'`：插件通过顶级 `plugins` 配置注册，作用于所有构建任务
+- `'pkg'`：插件通过 `pkgs[].plugins` 配置注册，仅作用于当前 pkg
+
+```js
+const plugin = (api) => {
+  const { pluginScope } = api;
+
+  if (pluginScope === 'pkg') {
+    // 仅在 pkg 级别执行的逻辑
+  } else {
+    // 全局执行的逻辑
+  }
+};
+```
+
+同一个插件可以同时被全局和 pkg 级别引用，通过 `pluginScope` 可以在插件内部针对不同场景执行不同的逻辑。
+
+### onGetConfig
+
+ICE PKG 会根据用户配置注册对应的构建任务，通过 `onGetConfig` API 可以修改每个任务的配置项。
+
+**不指定任务名**时，行为因插件注册方式不同而有所区别：
+
+- 通过顶级 `plugins` 注册的插件（`pluginScope: 'global'`）：修改会对**所有任务**生效
+- 通过 `pkgs[].plugins` 注册的插件（`pluginScope: 'pkg'`）：修改仅对**当前 pkg 的任务**生效，无法影响其他 pkg；若指定了其他 pkg 的任务名，会产生警告并被忽略
+
+**指定任务名**时，任务名与配置方式有关：
+
+使用 `pkgs` 配置时，任务名格式为 `{bundle|transform}-{id}`，其中 `id` 的生成逻辑如下：
+
+- 若 pkg 配置了 `id` 字段，则直接使用该值
+- 否则默认取 `module` 值（如 `esm`、`cjs`）
+- 若已有同名 id，则追加 `target`，变为 `{module}-{target}`（如 `esm-es2017`）
+- 若仍有冲突，则在末尾追加数字后缀（如 `esm-1`）
+
+例如以下配置：
+
+```ts title="build.config.mts"
+export default defineConfig({
+  pkgs: [
+    { module: 'esm', target: 'es2017' }, // 任务名：transform-esm
+    { module: 'esm', target: 'es5' }, // 任务名：transform-esm-es5（已有 esm，追加 target）
+    { id: 'my-cjs', module: 'cjs', bundle: true }, // 任务名：bundle-my-cjs（使用自定义 id）
+  ],
+});
+```
+
+:::caution
+`pkgs` 的任务名由运行时动态生成，可能因配置顺序变化而改变。建议通过**不指定任务名**的方式让修改对所有任务生效，仅在确实需要精准定位某个任务时才依赖任务名，并配合显式 `id` 字段保证稳定性。
+:::
+
+使用传统 `transform.formats` / `bundle.formats` 时，任务名规则如下：
+
+- `transform-esm`：默认启动
+- `transform-es2017`：默认启动
+- `transform-cjs`：当 Transform 配置了 `formats: ['cjs']` 启动
+- `bundle-es5`：当 Bundle 配置了 `formats: ['esm']` 或者 `formats: ['cjs']` 或者 `formats: ['umd']` 时启动
+- `bundle-es2017`：当 Bundle 配置了 `formats: ['es2017']` 时启动
+
+通过 `onGetConfig` API，可以修改每个 Task 任务的配置项。
+
+当不指定任务名时，修改的配置会对所有任务生效：
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  // 不指定 Task name
+  onGetConfig((config) => {
+    return {
+      ...config,
+      entry: './component/index',
+    };
+  });
+};
+```
+
+你也可以指定修改某个任务的配置，比如：
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  // 仅仅修改 transform-esm 任务的配置
+  onGetConfig('transform-esm', (config) => {
+    return {
+      ...config,
+      entry: './component/index',
+    };
+  });
+};
+```
+
+有以下参数可以配置：
+
+#### entry
+
+- 类型：`string | string[] | { [entryAlias: string]: string }`
+- 默认值：`'./src/index'`
+
+指定构建入口。支持配置单入口或者多个入口。
+
+指定单个入口：
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    return {
+      ...config,
+      entry: './component/index',
+    };
+  });
+};
+```
+
+指定多个入口：
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    return {
+      ...config,
+      // 1. 数组形式
+      entry: ['./src/foo', './src/bar'],
+      // 2. 对象形式，key 值作为 chunk name
+      entry: {
+        foo: './src/foo',
+        bar2: './src/bar',
+      },
+    };
+  });
+};
+```
+
+#### define
+
+- 类型：`Record<string, string>`
+- 默认值：`{ 'process.env.NODE_ENV': 'development' | 'production', __DEV__: true | false }`
+
+定义编译时环境变量，会在编译时被替换。注意：属性值会经过一次 `JSON.stringify()` 转换。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    return {
+      ...config,
+      define: {
+        VERSION: '1.0.0',
+      },
+    };
+  });
+};
+```
+
+#### sourcemap
+
+- 类型：`boolean | 'inline'`
+- 默认值：start 阶段为 `true`，build 阶段为 `false`
+
+配置是否生成源码调试映射。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    return {
+      ...config,
+      sourcemap: true,
+    };
+  });
+};
+```
+
+#### alias
+
+- 类型：`Record<string, string>`
+- 默认值：`{}`
+
+配置模块引入的别名。比如，将 `@` 指向 `./src` 目录：
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    return {
+      ...config,
+      alias: {
+        '@': './src',
+      },
+    };
+  });
+};
+```
+
+然后代码里 `import '@/foo'` 会被改成 `import '/path/to/your/project/foo'`。
+
+#### modifyRollupOptions
+
+- 类型：`Array<(rollupOptions: RollupOptions) => RollupOptions>`
+- 默认值：`[]`
+
+修改默认的 [Rollup 选项](https://rollupjs.org/guide/en/#rolluprollup)。仅在使用 `rollup` 或 `rolldown` 引擎时生效。
+
+```js
+import svelte from 'rollup-plugin-svelte';
+
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    config.modifyRollupOptions ??= [];
+    config.modifyRollupOptions.push((rollupOptions) => {
+      rollupOptions.plugins.push(svelte({}));
+      return rollupOptions;
+    });
+  });
+};
+```
+
+#### modifyRslibConfig
+
+- 类型：`Array<(rslibConfig: RslibConfig) => RslibConfig>`
+- 默认值：`[]`
+
+修改默认的 [Rslib 配置](https://lib.rsbuild.dev/config/)。仅在使用 `rslib` 引擎时生效。支持直接修改传入的配置对象，也可以返回新的配置对象。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    config.modifyRslibConfig ??= [];
+    config.modifyRslibConfig.push((rslibConfig) => {
+      // 修改 rslib 配置
+      rslibConfig.output ??= {};
+      rslibConfig.output.cssModules = { localIdentName: '[hash:base64:8]' };
+      return rslibConfig;
+    });
+  });
+};
+```
+
+#### babelPlugins
+
+- 类型：`babel.PluginItem[] | undefined`
+- 默认值：`undefined`
+
+配置额外的 babel 插件。当配置此选项后，将会先使用 babel 对代码进行编译，然后再经过 swc 编译。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    config.babelPlugins = [];
+  });
+};
+```
+
+#### modifySwcCompileOptions
+
+- 类型：`(config: swc.Config) => swc.Config`
+- 默认值：`undefined`
+
+用于修改 SWC 编译选项，函数入参是内置的 SWC 配置。具体编译选项可参考 [SWC 配置](https://swc.rs/docs/configuration/swcrc)。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    config.modifySwcCompileOptions = (originOptions) => {
+      const newOptions = { ...originOptions, env: {} };
+      return newOptions;
+    };
+  });
+};
+```
+
+#### swcCompileOptions
+
+- 类型：`swc.Config`
+- 默认值：`{}`
+
+:::tip
+推荐使用 [modifySwcCompileOptions](#modifyswccompileoptions) 来修改 SWC 编译选项。
+:::
+
+设置 SWC 编译选项，会与内置的选项合并。优先级低于 `modifySwcCompileOptions`。具体编译选项可参考 [SWC 配置](https://swc.rs/docs/configuration/swcrc)。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig((config) => {
+    config.swcCompileOptions = {
+      // config
+    };
+  });
+};
+```
+
+#### outputDir
+
+> 仅对 Bundle 模式生效。Transform 模式按照配置的 format 值分别输出到对应目录，比如 esm、cjs、es2017
+
+- 类型：`string`
+- 默认值：`dist`
+
+配置 Bundle 模式下组件编译产物的输出目录。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    return {
+      ...config,
+      outputDir: 'build',
+    };
+  });
+};
+```
+
+#### modifyStylesOptions
+
+> 仅对 Bundle 模式生效
+
+- 类型 `Array<(options: StylesRollupPluginOptions) => StylesRollupPluginOptions>`
+- 默认值：`[]`
+
+ICE PKG 默认使用 [rollup-plugin-styles](https://www.npmjs.com/package/rollup-plugin-styles) 处理样式文件，可以通过 `modifyStylesOptions` 方式修改插件的配置。
+
+```js
+import PostcssPluginRpxToVw from 'postcss-plugin-rpx2vw';
+
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    config.modifyStylesOptions ??= [];
+    config.modifyStylesOptions.push((stylesOptions) => {
+      stylesOptions.plugins ||= [];
+      stylesOptions.plugins.push(PostcssPluginRpxToVw());
+      return stylesOptions;
+    });
+    return config;
+  });
+};
+```
+
+#### extensions
+
+> 仅对 Bundle 模式生效
+
+- 类型 `string[]`
+- 默认值：`['.mjs', '.js', '.json', '.node', '.jsx', '.ts', '.tsx', '.mts', '.cjs', '.cts']`
+
+配置解析的文件后缀名，这样在引入模块时不需要带后缀名，配置后会与默认值合并。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    config.extensions = ['.xtpl'];
+    return config;
+  });
+};
+```
+
+#### name
+
+> 仅对 Bundle 模式生效
+
+- 类型：`string`
+- 默认值：`package.name`
+
+Bundle 导出名称。一般用于 umd 产物中通过 `window[name]` 拿到产物模块内容。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    config.name = 'ICEPKG';
+    return config;
+  });
+};
+```
+
+#### modes
+
+> 仅对 Bundle 模式生效
+
+- 类型：`Array<'development' | 'production' | string>`
+- 默认值：`['production']`
+
+指定输出的产物是否经过压缩。默认情况下输出的产物是压缩过的（也就是开启了 `production`）。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    // 同时生成一份未压缩的产物和一份压缩产物
+    config.modes = ['development', 'production'];
+    return config;
+  });
+};
+```
+
+#### externals
+
+> 仅对 Bundle 模式生效
+
+- 类型：`boolean | Record<string, string> | Array<string | RegExp | Record<string, string>>`
+- 默认值：`{}`
+
+设置哪些模块不打包，转而通过 `<script>` 或其他方式引入。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    return {
+      ...config,
+      externals: {
+        react: 'React',
+        'react-dom': 'ReactDOM',
+      },
+    };
+  });
+};
+```
+
+#### minify
+
+> 仅对 Bundle 模式生效
+
+- 类型：`boolean`
+- 默认值：start 阶段为 `false`，build 阶段为 `true`
+
+是否压缩 JS 和 CSS 产物。
+
+```js
+const plugin = (api) => {
+  const { onGetConfig } = api;
+  onGetConfig('bundle-es5', (config) => {
+    return {
+      ...config,
+      minify: false,
+    };
+  });
+};
+```
+
+### onHook
+
+通过 `onHook` 监听命令构建时事件，`onHook` 注册的函数执行完成后才会执行后续操作，可以用于在命令运行中途插入插件想做的操作：
+
+```js
+const plugin = (api) => {
+  const { onHook } = api;
+  onHook('after.build.compile', (args) => {
+    console.log(args.taskName, '编译结束');
+  });
+};
+```
+
+ICE PKG 插件提供以下生命周期钩子：
+
+- build 命令：
+
+| 生命周期            | 参数                                                                                                                                       | 调用时机           |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
+| before.build.load   | `{ args: CommandArgs; config: PkgConfig[] }`                                                                                               | 获取所有任务配置后 |
+| before.build.run    | `{ args: CommandArgs; config: PkgConfig[] }`                                                                                               | 编译执行之前       |
+| after.build.compile | `{ taskName: string; outputFiles: OutputFile[]; outputs?: Array<rollup.RollupOutput['output']>; modules?: rollup.RollupCache['modules'] }` | 编译结束           |
+
+- start 命令
+
+| 生命周期            | 参数                                                                             | 调用时机           |
+| ------------------- | -------------------------------------------------------------------------------- | ------------------ |
+| before.start.load   | `{ args: CommandArgs; config: PkgConfig[] }`                                     | 获取所有任务配置后 |
+| before.start.run    | `{ args: CommandArgs; config: PkgConfig[]  }`                                    | 编译执行之前       |
+| after.start.compile | `{ taskName: string; outputFiles: OutputFile[]; modules?: rollup.ModuleJSON[] }` | 编译结束           |
+
+### registerTask
+
+添加自定义 Task 任务：
+
+```js
+const plugin = (api) => {
+  const { registerTask } = api;
+  registerTask('transform-cjs', {
+    type: 'transform', // 必填
+  });
+};
+```
+
+### getAllTask
+
+获取所有 Task 任务：
+
+```js
+const plugin = (api) => {
+  const { getAllTask } = api;
+  const tasks = getAllTask();
+};
+```
+
+### modifyUserConfig
+
+修改用户配置内容：
+
+```js
+const plugin = (api) => {
+  const { modifyUserConfig } = api;
+  modifyUserConfig(key, value);
+};
+```
+
+### registerUserConfig
+
+为 `build.config.mts` 配置文件添加自定义字段：
+
+```js
+const plugin = (api) => {
+  const { registerUserConfig } = api;
+  registerUserConfig({
+    name: 'custom-key',
+    validation: 'boolean' // 可选，支持类型有 string, number, array, object, boolean
+    setConfig: () => {
+      // 该字段对于配置的影响，通过 onGetConfig 设置
+    },
+  });
+};
+```
diff --git a/website/docs/plugin/usage.md b/website/docs/plugin/usage.md
new file mode 100644
index 00000000..997dbb9e
--- /dev/null
+++ b/website/docs/plugin/usage.md
@@ -0,0 +1,84 @@
+# 使用插件
+
+ICE PKG 基于 [build-scripts](https://github.com/ice-lab/build-scripts) 插件系统，通过插件可以极大地扩展 ICE PKG 的构建能力。
+
+## 配置插件
+
+在 `build.config.mts` 中通过 [`plugins`](../config/plugins) 配置项引入插件：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    // 从 npm 安装的插件
+    '@ice/plugin-docusaurus',
+    // 本地插件（相对路径）
+    './my-plugin.mjs',
+    // 带选项的插件
+    ['@ice/plugin-docusaurus', { title: 'My Docs' }],
+  ],
+});
+```
+
+部分插件支持通过 `import` 引入后使用，可以提供更好的类型提示能力，例如：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+import myPlugin from 'my-plugin';
+
+export default defineConfig({
+  plugins: [myPlugin({ foo: 'bar' })],
+});
+```
+
+两种用法的区别在于插件的导出形式。使用前请仔细阅读插件文档，确认插件支持哪种引入方式。
+
+## 本地插件
+
+如果只需要在当前项目中使用，可以直接创建本地插件文件，通过相对路径引入：
+
+```js title="my-plugin.mjs"
+/**
+ * @type {import('@ice/pkg').Plugin}
+ */
+const plugin = (api, options) => {
+  // 在这里编写插件逻辑
+  console.log('plugin options:', options);
+};
+
+export default plugin;
+```
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [['./my-plugin.mjs', { foo: 'bar' }]],
+});
+```
+
+## pkg 级别插件
+
+通过 [`pkgs`](../config/pkgs) 配置的每个构建单元也支持独立配置插件，仅对当前 pkg 生效：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  pkgs: [
+    {
+      module: 'esm',
+      plugins: ['./esm-only-plugin.mjs'],
+    },
+  ],
+});
+```
+
+:::caution
+插件通常只支持其中一种作用域，混用可能导致行为异常。在使用插件前，请查阅插件文档确认其支持的作用域：
+
+- **仅支持全局**：只能配置在顶级 `plugins` 中，例如文档类插件（`@ice/plugin-docusaurus`）需要注册全局构建钩子，放到 `pkgs[].plugins` 中会不生效
+- **仅支持 pkg 级别**：只能配置在 `pkgs[].plugins` 中，放到顶级 `plugins` 中会不生效
+- **两者均支持**：可在两处配置，插件内部会通过 `pluginScope` 区分当前运行环境
+  :::
diff --git a/website/docs/quick-start.md b/website/docs/quick-start.md
index 844544c7..99d587ac 100644
--- a/website/docs/quick-start.md
+++ b/website/docs/quick-start.md
@@ -4,7 +4,7 @@
 
 ### 1. Node.js
 
-使用 ICE PKG 开发前需要安装 [Node.js](https://nodejs.org)，并确保 node 版本是 16.14 或以上。
+使用 ICE PKG 开发前需要安装 [Node.js](https://nodejs.org)，并确保 node 版本是 18 或以上，推荐使用 20。
 
 ### 2. 包管理工具
 
@@ -27,11 +27,12 @@ $ npm init @ice/pkg@latest react-component
 ```
 
 选择 React 组件项目类型：
+
 ```bash
 ? 请选择项目类型 (Use arrow keys)
 ❯ React 组件
   Node 模块
-  前端类库  
+  前端类库
   Rax 组件
 ```
 
@@ -48,13 +49,7 @@ $ cd react-component
 $ npm start
 ```
 
-现在，访问 `http://localhost:4000`，即可查看组件 README 文档：
-
-![demo-readme](https://img.alicdn.com/imgextra/i2/O1CN01OctOw81JXuHCC6FhP_!!6000000001039-2-tps-1110-720.png)
-
-访问 `http://localhost:4000/usage`，即可预览组件：
-
-![component-preview](https://img.alicdn.com/imgextra/i3/O1CN01uEHuWp1DtXHv6uwax_!!6000000000274-2-tps-1160-540.png)
+默认情况下会启动 transform 构建模式，可以根据你的诉求新增新的构建目标。
 
 ## 生成构建产物
 
@@ -66,7 +61,22 @@ $ npm run build
 
 1. 在 `package.json` 中修改包名
 
-2. 执行发布命令：
+2. 确认 `package.json` 中的 `exports`/`main` 字段已正确指向构建产物，例如：
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./es2017/index.js",
+      "default": "./es2017/index.js"
+    }
+  }
+}
+```
+
+更多配置说明请参考 [React 组件 — 发布配置](./guide/scenario/react#发布配置)。
+
+3. 执行发布命令（npm 会先自动执行 `prepublishOnly` 脚本完成构建）：
 
 ```bash
 $ npm publish
diff --git a/website/docs/reference/cli.md b/website/docs/reference/cli.md
deleted file mode 100644
index 90b0d3a7..00000000
--- a/website/docs/reference/cli.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# CLI
-
-## start
-
-启动本地调试服务。
-
-```bash
-$ ice-pkg start [options]
-```
-|     选项     |   类型    | 说明                          |
-| :----------: | :-------: | ----------------------------- |
-| `--config <config>` | `string` | 指定配置文件路径 |
-| `--rootDir <rootDir>` | `string` | 指定应用运行的根目录 |
-| `--analyzer` | `boolean` | Bundle 模式下开启体积构建分析 |
-
-## build
-
-执行编译或者打包构建，输出构建产物。
-
-
-```bash
-$ ice-pkg build [options]
-```
-
-|     选项     |   类型    | 说明                          |
-| :----------: | :-------: | ----------------------------- |
-| `--config <config>` | `string` | 指定配置文件路径 |
-| `--rootDir <rootDir>` | `string` | 指定应用运行的根目录 |
-| `--analyzer` | `boolean` | Bundle 模式下开启体积构建分析 |
diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts
index c0cd9e4f..31aa149e 100644
--- a/website/docusaurus.config.ts
+++ b/website/docusaurus.config.ts
@@ -20,33 +20,19 @@ const config: Config = {
       {
         docs: {
           sidebarPath: path.resolve('./sidebars.js'),
-          sidebarItemsGenerator: async () => {
-            return [
-              { type: 'doc', id: 'index' },
-              { type: 'doc', id: 'quick-start' },
-              { type: 'doc', id: 'guide/abilities' },
-              { type: 'doc', id: 'guide/scenarios' },
-              { type: 'doc', id: 'guide/build' },
-              { type: 'doc', id: 'guide/publish' },
-              { type: 'doc', id: 'guide/test' },
-              { type: 'doc', id: 'guide/preview' },
-              { type: 'doc', id: 'guide/mf' },
-              { type: 'doc', id: 'guide/jsx-plus' },
-              { type: 'doc', id: 'guide/monorepo' },
-              {
-                type: 'category',
-                label: '参考',
-                items: [
-                  { type: 'doc', id: 'reference/cli' },
-                  { type: 'doc', id: 'reference/config' },
-                  { type: 'doc', id: 'reference/plugins-development' },
-                ],
-              },
-              { type: 'doc', id: 'faq', label: '常见问题' },
-            ];
-          },
           routeBasePath: '/',
           editUrl: 'https://github.com/ice-lab/icepkg/tree/main/website/docs',
+          lastVersion: 'current',
+          versions: {
+            current: {
+              label: 'v2',
+              path: '/',
+            },
+            v1: {
+              label: 'v1',
+              path: '/v1',
+            },
+          },
         },
         blog: false,
         theme: {},
@@ -68,26 +54,23 @@ const config: Config = {
       },
       items: [
         { type: 'search', position: 'right' },
+        { type: 'docSidebar', sidebarId: 'tutorialSidebar', label: '使用', position: 'left' },
+        { type: 'docSidebar', sidebarId: 'configSidebar', label: '配置', position: 'left' },
         {
-          label: '生态',
+          label: '生态与资源',
           position: 'right',
           items: [
             { label: '应用研发框架 ICE', to: 'https://v3.ice.work/' },
             { label: '微前端 ICESTARK', to: 'https://micro-frontends.ice.work/' },
             { label: '可视化工具 AppWorks', to: 'https://appworks.site/' },
             { label: '前端环境 AppToolkit', to: 'https://github.com/appworks-lab/toolkit#readme' },
-          ],
-        },
-        {
-          label: '资源',
-          position: 'right',
-          items: [
-            { to: 'https://fusion.design/pc/doc/component/102', label: 'Fusion 组件' },
-            { to: 'https://ant.design', label: 'Antd 组件' },
+            { label: 'Fusion 组件', to: 'https://fusion.design/pc/doc/component/102' },
+            { label: 'Antd 组件', to: 'https://ant.design' },
             { label: '社区钉钉群', to: 'https://iceworks.oss-cn-hangzhou.aliyuncs.com/assets/images/ice-group.png' },
           ],
         },
         { href: 'https://github.com/ice-lab/icepkg', label: 'GitHub', position: 'right' },
+        { type: 'docsVersionDropdown', position: 'right' },
       ],
     },
 
@@ -126,6 +109,16 @@ const config: Config = {
     },
   },
 
+  plugins: [
+    [
+      'docusaurus-plugin-llms',
+      {
+        generateLLMsTxt: true,
+        generateLLMsFullTxt: true,
+      },
+    ],
+  ],
+
   themes: [
     [
       '@easyops-cn/docusaurus-search-local',
diff --git a/website/package.json b/website/package.json
index 60be790f..f12a93a5 100644
--- a/website/package.json
+++ b/website/package.json
@@ -31,6 +31,7 @@
     "@docusaurus/types": "^3.0.0",
     "@tsconfig/docusaurus": "^2.0.0",
     "@types/react": "^18.0.0",
+    "docusaurus-plugin-llms": "^0.3.1",
     "typescript": "catalog:"
   },
   "browserslist": {
diff --git a/website/sidebars.js b/website/sidebars.js
index 8676f2f6..06f3b6fb 100644
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -1,3 +1,76 @@
 module.exports = {
-  tutorialSidebar: [{ type: 'autogenerated', dirName: '.' }],
+  configSidebar: [
+    { type: 'doc', id: 'config/index' },
+    { type: 'doc', id: 'config/entry' },
+    { type: 'doc', id: 'config/alias' },
+    { type: 'doc', id: 'config/define' },
+    { type: 'doc', id: 'config/source-maps' },
+    { type: 'doc', id: 'config/jsx-runtime' },
+    { type: 'doc', id: 'config/plugins' },
+    { type: 'doc', id: 'config/helpers' },
+    { type: 'doc', id: 'config/declaration' },
+    { type: 'doc', id: 'config/server' },
+    { type: 'doc', id: 'config/transform' },
+    { type: 'doc', id: 'config/bundle' },
+    { type: 'doc', id: 'config/pkgs' },
+  ],
+
+  tutorialSidebar: [
+    { type: 'doc', id: 'index' },
+    { type: 'doc', id: 'quick-start' },
+    {
+      type: 'category',
+      label: '场景',
+      collapsed: false,
+      items: [
+        { type: 'doc', id: 'guide/scenario/react' },
+        { type: 'doc', id: 'guide/scenario/node' },
+        { type: 'doc', id: 'guide/scenario/library' },
+      ],
+    },
+    {
+      type: 'category',
+      label: '基础',
+      collapsed: false,
+      items: [
+        { type: 'doc', id: 'guide/configure' },
+        { type: 'doc', id: 'guide/build-modes' },
+        { type: 'doc', id: 'guide/build' },
+      ],
+    },
+    {
+      type: 'category',
+      label: '进阶',
+      collapsed: false,
+      items: [
+        { type: 'doc', id: 'guide/typescript' },
+        { type: 'doc', id: 'guide/css' },
+        { type: 'doc', id: 'guide/engine' },
+        { type: 'doc', id: 'guide/mf' },
+        { type: 'doc', id: 'guide/jsx-plus' },
+        { type: 'doc', id: 'guide/monorepo' },
+        { type: 'doc', id: 'guide/test' },
+        { type: 'doc', id: 'guide/server' },
+        { type: 'doc', id: 'guide/preview' },
+      ],
+    },
+    {
+      type: 'category',
+      label: '插件',
+      collapsed: false,
+      items: [
+        { type: 'doc', id: 'plugin/usage' },
+        { type: 'doc', id: 'plugin/development' },
+      ],
+    },
+    { type: 'doc', id: 'cli' },
+    { type: 'doc', id: 'faq' },
+    { type: 'doc', id: 'ai' },
+    {
+      type: 'category',
+      label: '迁移',
+      collapsed: false,
+      items: [{ type: 'doc', id: 'migration/v1-to-v2' }],
+    },
+  ],
 };
diff --git a/website/versioned_docs/version-v1/faq.md b/website/versioned_docs/version-v1/faq.md
new file mode 100644
index 00000000..7f362f25
--- /dev/null
+++ b/website/versioned_docs/version-v1/faq.md
@@ -0,0 +1,36 @@
+# 常见问题
+
+## 为什么需要依赖 `@ice/jsx-runtime`
+
+`@ice/pkg` 在 v1.5.0 版本以后，为支持能在内联样式中使用 rpx 单位，组件需要依赖 `@ice/jsx-runtime` 才能正常渲染。
+
+```jsx
+const Home = () => {
+  return <div style={{ fontSize: '100rpx' }}>Home</div>;
+};
+```
+
+因此，Transform 模式下，需要 `@ice/jsx-runtime` 作为项目的 `dependencies`；Bundle 模式下需要把 `@ice/jsx-runtime` 作为项目的 `devDependencies`
+
+```bash
+# Transform 模式
+$ npm i @ice/jsx-runtime --save
+# Bundle 模式
+$ npm i @ice/jsx-runtime --save-dev
+```
+
+## 为什么需要依赖 `@swc/helpers`
+
+:::caution
+`@ice/pkg` 1.5.6 版本升级 `@swc/core` 到 1.3.55 版本，需将项目中的 `@swc/helpers` 同时升级到 ^0.5.0 版本
+:::
+
+Transform 模式的产物代码中可能依赖一些 helper 函数用以支持目标环境。ICE PKG 默认将这些 helper 函数统一从 `@swc/helpers` 中导出使用，以减小产物代码体积。因此，当你的产物代码中引用了 `@swc/helpers` 时，请务必将 `@swc/helpers` 作为项目的 `dependencies`。
+
+```bash
+$ npm i @swc/helpers --save
+```
+
+## `Error: Can't resolve 'sass-loader' in ...`
+
+出现这个报错的原因是在使用 docusaurus 插件时，docusaurus 无法正常 resolve 到 `sass-loader` 依赖。请更新 `@ice/pkg-plugin-docusaurus` 到最新版本。
diff --git a/website/docs/guide/Button.tsx b/website/versioned_docs/version-v1/guide/Button.tsx
similarity index 100%
rename from website/docs/guide/Button.tsx
rename to website/versioned_docs/version-v1/guide/Button.tsx
diff --git a/website/docs/guide/abilities.md b/website/versioned_docs/version-v1/guide/abilities.md
similarity index 93%
rename from website/docs/guide/abilities.md
rename to website/versioned_docs/version-v1/guide/abilities.md
index a77c6097..7baddb02 100644
--- a/website/docs/guide/abilities.md
+++ b/website/versioned_docs/version-v1/guide/abilities.md
@@ -1,4 +1,4 @@
-# 构建能力
+# 双模式
 
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
@@ -46,13 +46,6 @@ esm
 
 Transform 模式下输出的产物具有较好的调试性，并且对 Tree-Shaking 友好。适用于大部分开发 React/Rax 组件或者 Node 模块场景。
 
-当配置了多个 entry 时，Transform 只会处理 entry 作用域内的文件，不会隐式处理未配置目录。你可以通过 `transform.entryRoot` 控制输出路径的相对根目录。例如，entry 为 `./src/a/b/c/index.ts` 时：
-
-- `entryRoot: './src/a/b'` 输出 `esm/c/index.js`
-- `entryRoot: './src'` 输出 `esm/a/b/c/index.js`
-
-若使用 `pkgs`，可在具体 pkg 上配置 `entryRoot`，其优先级高于全局 `transform.entryRoot`。
-
 ### Bundle 模式
 
 Bundle 模式即以入口文件作为起点，递归处理各种模块，最终把相同类型的文件合并成一个构建产物。目前 [Webpack](https://webpack.js.org/)、[Rollup](https://rollupjs.org) 等就是对源码进行打包构建的工具。
diff --git a/website/versioned_docs/version-v1/guide/build.md b/website/versioned_docs/version-v1/guide/build.md
new file mode 100644
index 00000000..605d6f22
--- /dev/null
+++ b/website/versioned_docs/version-v1/guide/build.md
@@ -0,0 +1,192 @@
+# 构建产物
+
+本文讲述不同[构建模式](./abilities#双模式构建)下的产物说明以及适用的场景。完整的产物构建配置可查看文档 [Transform 模式构建配置](../reference/config#transform)和 [Bundle 模式构建配置](../reference/config#bundle)。
+
+## 构建产物说明
+
+ICE PKG 默认支持 `esm`、`es2017`、`cjs`、`umd` 四种构建产物类型。每种产物类型在不同构建模式下支持情况、模块规范、语法规范说明如下表：
+
+| 产物类型 | Transform 模式 | Bundle 模式 | 模块规范  | 语法规范 |
+| :------: | :------------: | :---------: | :-------: | :------: |
+|  `esm`   |     ✅支持     |   ✅支持    | ES Module |   ES5    |
+| `es2017` |     ✅支持     |   ✅支持    | ES Module |  ES2017  |
+|  `cjs`   |     ✅支持     |   ✅支持    | CommonJS  |   ES5    |
+|  `umd`   |    ❌不支持    |   ✅支持    |    UMD    |   ES5    |
+
+每种构建产物的优缺点和适用场景如下表所示：
+
+| 产物类型 | 优点                               | 缺点     | 适用场景                                                                                                               |
+| :------: | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------- |
+|  `esm`   | 兼容性较好                         | 体积大   | 消费产物的应用打包时不编译 `node_modules`；或者运行环境支持的 ECMAScript 版本较低                                      |
+| `es2017` | 保留大部分 JavaScript 语法，体积小 | 兼容性差 | 消费产物的应用打包时编译 `node_modules`；或者运行环境支持的 ES2017 语法。更多说明可参考[文档](./abilities#es2017-产物) |
+|  `cjs`   | 兼容各版本的 Node.js               | 体积大   | 在 Node.js 环境下运行                                                                                                  |
+|  `umd`   | 兼容运行在浏览器和 Node.js 中      | 体积大   | 用户的项目中某个依赖 external，需要在 HTML 中通过 `<script />` 引入 UMD 产物；或者在浏览器中直接使用产物               |
+
+## 默认构建产物
+
+下面是 ICE PKG 默认的产物构建配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    formats: ['esm', 'es2017'],
+  },
+});
+```
+
+默认情况下，ICE PKG 只启用 Transform 模式并将产物分别输出到 `esm` 目录和 `es2017` 目录。
+
+执行 `npm run build` 命令后，得到以下的构建产物：
+
+```md
+── es2017
+| ├── index.d.ts
+| └── index.js
+├── esm
+| ├── index.d.ts
+| └── index.js
+```
+
+输出构建目录名和构建产物类型一一对应。
+
+对于 React 组件来说，它们会在应用中消费，而应用通常是会被打包工具打包后才能在生产环境中使用。以 Webpack 举例，可以配置 `resolve.conditionNames = ['es2017', 'esm']`，这样会优先使用 es2017 产物，配合在 `browserslist` 中配置高版本的浏览器（比如中后台场景），打包出来的产物能直接运行在目标浏览器，体积也会更小。
+
+## 构建现代产物
+
+如果你确定你的运行环境支持 [ES2017 产物](./abilities#es2017-产物)，推荐使用以下的配置仅生成体积更小的构建产物：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    formats: ['es2017'],
+  },
+  bundle: {
+    formats: ['esm', 'es2017'],
+  },
+});
+```
+
+> [Transform 模式](./abilities#transform-模式)和 [Bundle 模式](./abilities#bundle-模式)均支持生成 ES2017 产物。你可以根据实际的需求，选择启动单个模式或者双模式。
+
+构建产物如下：
+
+```md
+── es2017
+| ├── index.d.ts
+| └── index.js
+├── dist
+| └── index.esm.es2017.production.js
+```
+
+## ES Module 和 CommonJS 产物
+
+这种场景下是针对要生成运行在 Node.js 环境下的产物。如果你的产物需要兼容低版本 Node.js (v12.20.0 以下)，则还是需要生成 CommonJS 产物，否则可以直接使用 ES Module 的产物。
+
+:::tip
+不同版本的 Node.js 支持的 ECMAScript 语法可参考 [Node Green 网站](https://node.green/)。
+:::
+
+由于 Node 12.20.0 支持 ES Module 和所有的 ES2017 的语法。因此推荐以下的配置：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  transform: {
+    formats: ['cjs', 'es2017'],
+  },
+  bundle: {
+    formats: ['cjs', 'esm', 'es2017'],
+  },
+});
+```
+
+> [Transform 模式](./abilities#transform-模式)和 [Bundle 模式](./abilities#bundle-模式) 均支持生成 ES2017 产物和 CommonJS 产物。你可以根据实际的需求，选择启动单个模式或者双模式。
+
+执行 `npm run build` 后输出的产物如下：
+
+```md
+── cjs
+| ├── index.d.ts
+| └── index.js
+├── es2017
+| ├── index.d.ts
+| └── index.js
+├── dist
+| ├── index.cjs.es5.production.js
+| └── index.esm.es2017.production.js
+```
+
+其中，`cjs` 目录和 `es2017` 目录是 Transform 构建模式的产物；`dist` 目录是 Bundle 构建模式的产物。
+
+| 产物类型 | 模块规范  | 语法规范 |
+| :------: | --------- | -------- |
+|  es2017  | ES Module | ES2017   |
+|   cjs    | CommonJS  | ES5      |
+
+然后在 `package.json` 中配置 `exports` 产物导出：
+
+```json
+{
+  "exports": {
+    ".": {
+      "import": "./es2017/index.js",
+      "require": "./cjs/index.js",
+      "default": "./cjs/index.js"
+    }
+  }
+}
+```
+
+## UMD 产物
+
+一般情况下，[前端类库](./scenarios#前端类库)的场景需要打包构建生成 UMD 产物。
+
+ICE PKG 仅支持在 [Bundle 模式](./abilities#bundle-模式)下构建出 UMD 产物，配置方式如下：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    formats: ['umd'],
+    name: 'my-library', // 配置 umd 模块导出的名字，通过 `window[name]` 访问
+  },
+});
+```
+
+执行 `npm run build` 后，将会输出以下的构建结果：
+
+```md
+dist
+├── index.umd.es5.production.css
+└── index.umd.es5.production.js
+```
+
+如果需要额外输出一份未压缩的 UMD 产物以方便调试构建，可以新增 [bundle.modes 配置项](../reference/config#modes)：
+
+```diff title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  bundle: {
+    formats: ['umd'],
+    name: 'my-library',
++   modes: ['production', 'development'],
+  }
+})
+```
+
+执行 `npm run build` 后，将会输出以下的构建结果：
+
+```md
+dist
+├── index.umd.es5.development.css
+├── index.umd.es5.development.js
+├── index.umd.es5.production.css
+└── index.umd.es5.production.js
+```
diff --git a/website/versioned_docs/version-v1/guide/jsx-plus.md b/website/versioned_docs/version-v1/guide/jsx-plus.md
new file mode 100644
index 00000000..79750eb2
--- /dev/null
+++ b/website/versioned_docs/version-v1/guide/jsx-plus.md
@@ -0,0 +1,171 @@
+# JSX+
+
+该插件支持了一种 JSX 扩展语法 JSX+，它能帮助业务开发者更爽更快地书写 JSX。JSX+ 不是一种新的概念，它是 JSX 基础上的扩展指令概念。
+
+## 为什么需要 JSX+
+
+- JSX 虽然语法灵活，但是大量的花括号 + JS 语法导致了上下文切换和代码可读性的下降，JSX+ 的指令很好的解决了这个问题
+- JSX 本质是 JS 表达式，在运行时阶段才可以计算出真实的 DOM 结构，JSX+ 引入了一部分静态模板特性可以满足编译优化
+- 不新创造实体，指令在社区中是已经被广泛接受的概念，对开发者更友好，语法糖的表达更简单
+- 统一一套 JSX+ 类似概念的语法规范，减少已存在和潜在的重复建设
+
+## 安装使用
+
+首先需要安装依赖：
+
+```bash
+$ npm i babel-runtime-jsx-plus --save
+$ npm i @ice/pkg-plugin-jsx-plus --save-dev
+```
+
+然后把 jsx+ 插件加入到配置文件中：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [['@ice/pkg-plugin-jsx-plus']],
+});
+```
+
+然后你就可以使用更强大的 JSX+ 语法了：
+
+```jsx
+function ExampleComponent(props) {
+  const { isAdmin, dataSource } = props;
+
+  return (
+    <div>
+      <div x-if={isAdmin}>admin</div>
+      <div x-else>guest</div>
+
+      <div x-for={item in dataSource}>
+        <span>{item.name}</span>
+      </div>
+    </div>
+  );
+}
+```
+
+## 指令语法
+
+### 条件判断
+
+```jsx
+<div x-if={condition}>Hello</div>
+<div x-elseif={anotherCondition}>World</div>
+<div x-else>NothingElse</div>
+```
+
+:::tip
+`x-elseif` 可以多次出现，但是顺序必须是 x-if -> x-elseif -> x-else，且这些节点是兄弟节点关系，如顺序错误则指令被忽略。
+:::
+
+### 循环列表
+
+```jsx
+{/* Array or Plain Object*/}
+<tag x-for={item in foo}>{item}</tag>
+
+<tag x-for={(item, key) in foo}>{key}: {item}</tag>
+```
+
+说明：
+
+1. 若循环对象为数组，key 表示循环索引，其类型为 Number。
+2. 当 `x-for` 与 `x-if` 同时作用在同一节点上时，循环优先级大于条件，即循环的 `item` 和 `index` 可以在子条件判断中使用。
+
+### 单次渲染
+
+仅在首次渲染时会触发 `createElement` 并将其引用缓存，重新渲染时直接复用缓存，用于提高不带绑定节点渲染效率和 Diff 性能。
+
+```jsx
+<p x-memo>this paragragh {mesasge} content will not change.</p>
+```
+
+### 插槽指令
+
+类似 WebComponents 的 slot 概念，并提供插槽作用域。
+
+语法：
+
+```html
+<tag x-slot:slotName="slotScope" />
+```
+
+示例：
+
+```jsx
+// Example
+<Waterfall>
+  <view x-slot:header>header</view>
+  <view x-slot:item="props">{props.index}: {props.item}</view>
+  <view x-slot:footer>footer</view>
+</Waterfall>
+<slot name="header" /> // 槽位
+```
+
+对比传统 JSX：
+
+```jsx
+<Waterfall
+  renderHeader={() => (<view>header</view>)}
+  renderFooter={() => (<view>footer</view>)}
+  renderItem={(item, index) => (<view>{index}: {item}</view>}
+/>
+```
+
+对比小程序：
+
+```jsx
+<Waterfall>
+  <view slot="header">header</view>
+  <view slot="item" slot-scope="props">
+    {props.index}: {props.item}
+  </view>
+  <view slot="footer">footer</view>
+</Waterfall>
+```
+
+### Fragment 组件
+
+提供空组件，不产生 UI，提供绑定 `x-if` `x-for` `x-slot` 指令。
+
+```jsx
+<Fragment />
+```
+
+### 类名绑定
+
+语法：
+
+```jsx
+<div x-class={{ item: true, active: val }} />
+```
+
+参考实现：
+
+```jsx
+<div className={classnames({ item: true, active: val })} />
+```
+
+`classnames` 方法能力参考[同名 npm 包](https://npmjs.com/classnames)。
+
+> 更多请参考 [jsx-plus](https://github.com/jsx-plus/jsx-plus)
+
+## 插件选项
+
+### moduleName
+
+- 类型：`'react' | 'rax'`
+- 默认值：`'react'`
+
+指定当前从哪个模块中导入 `jsx.Fragment` 组件，以在转换 JSX+ 语法的时候从对应的模块中引入组件。比如如果使用 `rax`：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [['@ice/pkg-plugin-jsx-plus', { moduleName: 'rax' }]],
+});
+```
diff --git a/website/versioned_docs/version-v1/guide/monorepo.md b/website/versioned_docs/version-v1/guide/monorepo.md
new file mode 100644
index 00000000..91801fa5
--- /dev/null
+++ b/website/versioned_docs/version-v1/guide/monorepo.md
@@ -0,0 +1,229 @@
+# Monorepo
+
+ICE PKG 提供了对 Monorepo 方案的支持。目前支持：
+
+- 子项目之间依赖链接，方便进行本地调试
+- 结合类似 `Changesets`、`Rush` 等方案完成子项目版本管理和发布
+
+## 开发环境准备
+
+ICE PKG 的 Monorepo 方案是基于 [pnpm workspace](https://pnpm.io/workspaces) + 包构建器 [`@ice/pkg`](https://www.npmjs.com/package/@ice/pkg)，因此我们需要确保我们的开发环境满足：
+
+- [pnpm](https://pnpm.io/) 版本确保是 7 或以上
+- [node.js](https://nodejs.org) 版本确保是 16 或以上
+
+## 创建项目
+
+通过以下命令，可以快速初始化一个 Monorepo 项目：
+
+```bash
+$ pnpm create @ice/pkg my-monorepo
+```
+
+选择 React 组件项目类型：
+
+```bash
+? 请选择项目类型 (Use arrow keys)
+  React 组件
+  Node 模块
+  前端类库
+  Rax 组件
+❯ Monorepo React 组件
+  Monorepo Node 模块
+```
+
+## 目录介绍
+
+以一个多 React 组件默认脚手架项目为例子：
+
+```md
+├── build.config.mts # 文档预览配置文件
+├── package.json
+├── packages # 存放子项目的目录
+| ├── component-a
+| ├── component-b
+| └── component-c
+├── pages # 文档首页
+| ├── index.module.css
+| └── index.tsx
+├── pnpm-workspace.yaml # 定义工作空间的子项目
+├── tsconfig.base.json
+└── tsconfig.json
+```
+
+## 创建子项目
+
+在项目根目录下，执行以下命令创建一个子项目：
+
+```shell
+# 假设 packages 目录是用于存放子项目
+$ pnpm create @ice/pkg packages/your-lib --workspace
+```
+
+执行成功后，你将会看到以下内容：
+
+```shell
+? 请选择项目类型 (Use arrow keys)
+❯ React 组件
+  Node 模块
+  前端类库
+  Rax 组件
+```
+
+根据实际的需求选择对应的项目类型，然后填写子项目的 npm 包名后，完成子项目的创建。
+
+然后，我们还需要在根目录的 package.json 中 `devDependencies` 里添加依赖，以能正常启动文档预览服务（详细原因在后面[文档预览](#文档预览)小节中会讲到）：
+
+```diff
+# package.json
+{
+  "devDependencies": {
++   "@ali/your-lib": "workspace:*"
+  }
+}
+```
+
+## 本地调试
+
+在项目根目录下执行以下命令进行安装并构建工作区(workspace)的每个子项目：
+
+```bash
+$ pnpm install && pnpm packages:build
+```
+
+这个时候，所有的依赖都安装完成，并且有依赖的子项目之间也自动 link 好了。
+
+我们在项目根目录下执行以下命令启动调试：
+
+```bash
+$ pnpm start
+```
+
+这时会监听每个子项目的代码变更，并启动文档预览服务：
+
+![undefined](https://img.alicdn.com/imgextra/i2/O1CN01UwaC811GIqSgUoo7p_!!6000000000600-2-tps-1126-814.png)
+
+这时我们可以修改源码，进行本地调试了。
+
+## 文档预览
+
+文档预览服务基于 [`@ice/pkg-plugin-docusaurus`](./preview) ICE PKG 插件。推荐一个 Monorepo 项目存在一个文档站点服务，并支持预览所有的子项目的文档。
+
+### 添加依赖到根目录的 `package.json`
+
+由于启动文档本地预览调试是在项目的根目录进行，但在子项目的文档中通常直接依赖了子包，在文档进行打包构建的时候会找不到对应的子包，因此需要在项目根目录的 `package.json` 中添加对应的子项目依赖：
+
+```diff
+# package.json
+{
+  "devDependencies": {
++   "@ali/your-lib": "workspace:*"
+  }
+}
+```
+
+### 子项目文档预览
+
+`packages` 目录下每个子项目都会有一个 `docs` 目录，用来存放该子项目的文档。比如：
+
+```md
+./packages/component-a
+├── README.md
+├── build.config.mts
+├── docs
+| ├── index.md
+| ├── usage.md
+| └── usage.md
+├── package.json
+├── src
+└── tsconfig.json
+```
+
+在项目根目录下执行以下命令，会起一个 docusaurus 的文档预览：
+
+```shell
+$ pnpm docs:start
+```
+
+访问控制台中打印的文档地址就能查看文档了：
+
+![undefined](https://intranetproxy.alipay.com/skylark/lark/0/2023/png/301926/1673436424615-4d7bb212-8072-4a38-a644-21ca2a41fd34.png)
+
+以 `packages` 目录为根目录，页面的路由默认根据下每个子项目的文件路径自动生成的。比如上面的 `./packages/component-a/docs/index.md`，路由会自动为 `/component-a/docs/`（没有 `packages` 前缀）。
+
+所有的文档选项配置，都在根目录的 `build.config.mts` 文件中配置，下面是推荐的配置：
+
+```ts
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        path: 'packages',
+        sidebarItemsGenerator: (args: any) => {
+          // The index.md doc should not be the category, so we rewrite the default isCategoryIndex function.
+          function isCategoryIndex({ fileName, directories }: any) {
+            const eligibleDocIndexNames: string[] = ['readme', directories[0].toLowerCase()];
+            return eligibleDocIndexNames.includes(fileName.toLowerCase());
+          }
+          const defaultSidebarItems = args.defaultSidebarItemsGenerator({
+            ...args,
+            isCategoryIndex,
+          });
+          // 1. Remove the `docs` category.
+          // 2. Remove category link.
+          const newSidebarItems = defaultSidebarItems.map(({ link, ...rest }: any) => ({
+            ...rest,
+            items: rest.items.map((item: any) => item.items).flat(),
+          }));
+
+          return newSidebarItems;
+        },
+        exclude: ['**/node_modules/**'],
+        onBrokenLinks: 'warn',
+      },
+    ],
+  ],
+});
+```
+
+更多配置说明可参考[文档预览](https://pkg.ice.work/guide/preview)。
+
+### 定制文档首页
+
+默认情况下，当我们访问根路由(`/`)是返回 404 页面的。如果我们想定制文档首页的内容，我们可以增加 [`pageRouteBasePath`](./preview#pageroutebasepath) 配置：
+
+首先在 `build.config.mts` 中新增以下内容：
+
+```diff
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
++       pageRouteBasePath: '/',
+      },
+    ],
+  ],
+});
+```
+
+然后在根目录下新增 `pages` 目录，然后新增 `index.tsx` 或者` index.md` 文件，此文件将会被渲染到根路由。
+
+```tsx
+// pages/index.tsx
+export default function Home() {
+  return <div>我是首页</div>;
+}
+```
+
+## 发布
+
+对于 npm 包进行版本管理和发布，ICE PKG 推荐使用社区的版本控制工具：
+
+- [changesets](https://github.com/changesets/changesets)
+- [rush](https://rushjs.io/)
diff --git a/website/versioned_docs/version-v1/guide/preview.md b/website/versioned_docs/version-v1/guide/preview.md
new file mode 100644
index 00000000..395ad22e
--- /dev/null
+++ b/website/versioned_docs/version-v1/guide/preview.md
@@ -0,0 +1,713 @@
+# 文档预览
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+使用 [@ice/pkg-plugin-docusaurus](https://github.com/ice-lab/icepkg/tree/master/packages/plugin-docusaurus) 插件，依托 [Docusaurus](https://docusaurus.io/) 提供的能力，支持编写组件/库文档和预览组件。所有文档默认存放至 `docs` 文件夹下。支持以 `.md` 及 `.mdx` 为后缀的文档。
+
+在使用文档预览功能前，你需要先手动安装 `@ice/pkg-plugin-docusaurus` 插件：
+
+```shell
+$ npm install @ice/pkg-plugin-docusaurus --save-dev
+```
+
+并在配置文件中配置插件：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        title: '标题',
+      },
+    ],
+  ],
+});
+```
+
+大功告成。你可以通过以下命令启动预览：
+
+```shell
+# 若存在 docs 文件夹，则默认启动本地文档预览服务
+$ npm start
+
+# 若存在 docs 文件夹，则默认构建预览产物
+$ npm run build
+```
+
+## 关闭文档预览
+
+`@ice/pkg-plugin-docusaurus` 插件接受 `enable` 配置以决定是否启用文档预览，该值默认为 `true`。如果需要关闭文档预览，可以配置如下：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        enable: false,
+      },
+    ],
+  ],
+});
+```
+
+你也可以根据启动的命令来配置是否开启文档预览构建：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        // start 命令时启用文档预览，build 命令时关闭文档预览产物构建
+        enable: {
+          start: true,
+          build: false,
+        },
+      },
+    ],
+  ],
+});
+```
+
+## 如何书写文档
+
+文档以 `.md` 或 `.mdx` 为后缀，采用 [yaml](https://yaml.org/) 和 [markdown](https://daringfireball.net/projects/markdown/) 语法。
+
+````markdown title=index.md
+---
+title: 简单的用法
+sidebar_position: 1
+---
+
+## 本 Demo 演示一行文字的用法
+
+```tsx
+import * as React from 'react';
+import MyButton from 'my-button';
+import './my-button.css';
+
+const App = () => {
+  return (
+    <main>
+      <div>Hello World</div>
+      <MyButton />
+    </main>
+  );
+};
+
+export default App;
+```
+````
+
+### 文档结构
+
+#### 扁平结构
+
+扁平结构的意思是可以将文档平铺在 `docs` 文件夹下：
+
+```shell
+.
+├── index.md
+└── intro.md
+```
+
+#### 嵌套结构
+
+此外还支持嵌套结构，如：
+
+```shell
+.
+├── Foo
+│   ├── Basic.md
+│   └── Complex.md
+├── index.md
+└── intro.md
+```
+
+### 文档排序
+
+文档默认按照文件（或文件夹）的字母顺序进行排列。若要修改排列顺序，可通过下面两种方式。
+
+- 使用 `sidebar_position`
+
+可以在文档头部使用 [YAML](https://en.wikipedia.org/wiki/YAML) 标记顺序，比如想要将 `index.md` 设置为：
+
+```markdown
+---
+sidebar_position: 0
+---
+
+# 这是首页，同时也是标题
+
+在此处描述首页说明信息
+```
+
+- 文档添加数字前缀
+
+```shell
+.
+├── 01-intro.md
+├── 02-Foo
+│   ├── 01-Basic.md
+│   └── 02-Complex.md
+└── index.md
+```
+
+### 文档标题
+
+文档会默认使用第一个 markdown 标题，作为文档的 title。此外，可以通过 yaml 语法来修改文档标题：
+
+```markdown
+---
+sidebar_label: 这是标题
+---
+
+# 这里不再是默认标题了
+
+在此处描述文档内容...
+```
+
+### 代码块
+
+#### 将代码渲染成组件
+
+若想要预览组件，需要给代码块添加 `preview` 属性。
+
+````
+```tsx preview
+import * as React from 'react';
+import AddCount from './Button';
+
+const App = () => {
+  return (
+    <AddCount />
+  )
+}
+
+export default App;
+```
+````
+
+下面展示的就是给上述代码块添加 preview 的效果。
+
+```tsx preview
+import * as React from 'react';
+import AddCount from './Button';
+
+const App = () => {
+  return <AddCount />;
+};
+
+export default App;
+```
+
+> 需要注意的是，在 preview 的代码块中引入的样式会 **污染** 全局，因此建议使用 [CSS Modules](https://github.com/css-modules/css-modules) 或 [css-in-js](https://cssinjs.org/) 等方式引入样式。
+
+:::info 仅支持 React 组件和 Rax 组件
+目前只支持为 `jsx`、`tsx` 代码块添加 `preview` 属性。
+:::
+
+:::tip
+在 Markdown 代码块中编写代码会失去类型提示和类型校验。
+
+推荐使用 VSCode 插件 [TS in Markdown](https://marketplace.visualstudio.com/items?itemName=amour1688.ts-in-markdown) 以获得类型提示。
+
+推荐使用 `tsx` 代码块以获得类型校验，并需要确保在 `tsconfig.json` 中指定以下内容：
+
+```json
+{
+  "paths": {
+    // 假设 my-component 是你的组件名称
+    "my-component": ["./src"],
+    "my-component/*": ["./src/*"]
+  }
+}
+```
+
+:::
+
+#### 将代码块渲染成移动端预览的样式
+
+通过配置 `mobilePreview: true` 开启将预览方式设置成移动端预览的样式：
+
+```ts
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        mobilePreview: true,
+      },
+    ],
+  ],
+});
+```
+
+同理，所有添加了 [preview: true](#将代码渲染成组件) 的代码块会渲染成下面的样式：
+
+![](https://gw.alicdn.com/imgextra/i2/O1CN01UVaMo71q7gujCYGSc_!!6000000005449-2-tps-1338-761.png)
+
+#### 引入当前包的包名
+
+直接引入正在开发的包名 (package.json 中的 name 字段值)，像真实的用户一样在文档中导入你这在开发的包。比如你正在开发一个包名为 `my-button` 的组件：
+
+```tsx
+import * as React from 'react';
+// 假设 'my-button' 是你正在开发的包名
+import MyButton from 'my-button';
+
+export default function App() {
+  return <MyButton />;
+}
+```
+
+#### 给代码块定制自定义标题
+
+若想要给代码块定制自定义标题，可以使用 `title` 属性：
+
+````
+```tsx title=/src/components/index.jsx
+import * as React from 'react';
+import MyButton from 'my-button';
+
+export default function Index() {
+  return (
+    <MyButton />
+  );
+}
+```
+````
+
+文档渲染效果如下：
+
+```tsx preview
+import * as React from 'react';
+import MyButton from 'my-button';
+
+export default function Index() {
+  return (
+    <>
+      <MyButton>Hello</MyButton>
+    </>
+  );
+}
+```
+
+## 自动生成组件文档
+
+使用 `@ice/remark-react-docgen-docusaurus` 插件(基于 [react-docgen](https://github.com/reactjs/react-docgen/tree/5.x))可自动生成组件 Props 文档。
+
+首先我们需要先安装插件依赖：
+
+```bash
+$ npm i @ice/remark-react-docgen-docusaurus --save-dev
+```
+
+然后我们把插件增加到配置中：
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        remarkPlugins: ["require('@ice/remark-react-docgen-docusaurus')"],
+      },
+    ],
+  ],
+});
+```
+
+假设我们有这样的一个 Button 组件：
+<Tabs>
+
+<TabItem value="src/Button/index.tsx" label="src/Button/index.tsx">
+
+```tsx
+import * as React from 'react';
+import './index.scss';
+
+interface ButtonProps {
+  /**
+   * 设置按钮类型
+   */
+  type?: 'primary' | 'default';
+  /**
+   * 点击按钮时的回调
+   */
+  onClick: React.MouseEventHandler;
+}
+
+const Button: React.FunctionComponent<React.PropsWithChildren<ButtonProps>> = (props: ButtonProps) => {
+  const { type = 'default' } = props;
+  const typeCssSelector = {
+    primary: 'pkg-btn-primary',
+    default: 'pkg-btn-default',
+  };
+  return (
+    <button className={`pkg-btn ${typeCssSelector[type] || ''}`} onClick={props.onClick} data-testid="normal-button">
+      {props.children}
+    </button>
+  );
+};
+
+Button.defaultProps = {
+  type: 'default',
+};
+
+export default Button;
+```
+
+</TabItem>
+
+<TabItem value="src/Button/index.scss" label="src/Button/index.scss">
+
+```scss
+.pkg-btn {
+  border-radius: 6px;
+  height: 32px;
+  padding: 4px 15px;
+  font-size: 14px;
+  text-align: center;
+  border: 1px solid transparent;
+  cursor: pointer;
+  font-weight: 400;
+}
+
+.pkg-btn-primary {
+  color: #fff;
+  background-color: #1677ff;
+  box-shadow: 0 2px 0 rgb(5 145 255 / 10%);
+}
+
+.pkg-btn-default {
+  background-color: #fff;
+  border-color: #d9d9d9;
+  box-shadow: 0 2px 0 rgb(0 0 0 / 2%);
+}
+```
+
+</TabItem>
+</Tabs>
+
+然后我们在文档中加入以下内容：
+
+```mdx title="docs/button.md"
+## API
+
+<ReactDocgenProps path="../src/Button/index.tsx"></ReactDocgenProps>
+```
+
+`@ice/remark-react-docgen-docusaurus` 插件会识别到 `<ReactDocgenProps />` 组件来快速生成组件 Props 文档。效果图如下：
+
+![](https://img.alicdn.com/imgextra/i3/O1CN01xBo8CB1x4DI1PaSrF_!!6000000006389-0-tps-1196-428.jpg)
+
+:::caution
+目前有几点限制需要注意：
+
+1. 约定一个文件只能导出一个组件
+2. 无法解析从其他模块中导入的类型声明，因此只能在当前文件模块中声明组件的 Props 类型（[详见](https://github.com/reactjs/react-docgen/tree/5.x#flow-and-typescript-support)）
+3. 函数组件需要在函数入参中指定 props 类型，比如 `const Component = (props: ComponentProps) => {}`，否则无法解析
+4. 必须以 TSDoc 的形式书写注释（`// ` 形式的单行注释无法被提取）
+5. 默认值必须以 `Component.defaultProps = {}` 的形式书写，才能被工具提取
+   :::
+
+## 自定义侧边栏
+
+若你想要完全自定义侧边栏，比如有以下平铺结构：
+
+```shell
+├── index.md
+├── a.md
+├── b.md
+└── c.md
+```
+
+并试图将 `a.md`、`b.md` 和 `c.md` 收敛到一个 `示例` 的目录下，可以通过 `sidebarItemsGenerator` 进行配置：
+
+```ts
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        sidebarItemsGenerator: async () => {
+          return [
+            { type: 'doc', id: 'index' },
+            {
+              type: 'category', // 收敛到一个目录中
+              label: '实例', // 目录名
+              collapsed: false, // 目录是否折叠
+              items: [
+                { type: 'doc', id: 'a' },
+                { type: 'doc', id: 'b' },
+                { type: 'doc', id: 'c' },
+              ],
+            },
+          ];
+        },
+      },
+    ],
+  ],
+});
+```
+
+更多关于 `sidebarItemsGenerator` 的用法请见 [Docusaurus 文档](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#sidebarItemsGenerator)。
+
+## 自定义文档首页
+
+默认情况下，根路由显示的是 `README.md` 的内容。比如：
+
+![](https://img.alicdn.com/imgextra/i4/O1CN01rNo50g1hotnPKjSGi_!!6000000004325-2-tps-2250-1440.png)
+
+如果想定制首页，比如不带左侧侧边栏，可以加入以下的配置：
+
+```js title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        pageRouteBasePath: '/',
+        docsRouteBasePath: '/docs',
+      },
+    ],
+  ],
+});
+```
+
+然后在项目根目录下增加 pages 目录，新增 `index.tsx` 或者 `index.md` 文件，此文件将会被渲染到根路由。
+
+路由渲染规则请参考 [Docusaurus 文档](https://docusaurus.io/docs/creating-pages)。
+
+## 隐藏文档右侧导航
+
+在 [Mobile 组件预览](#将代码块渲染成移动端预览的样式) 下，若感觉整体内容区比较窄。或因为其他原因，想要隐藏右侧导航栏。可在文档顶部添加 `hide_table_of_contents` 这一配置。
+
+```md
+---
+hide_table_of_contents: true
+---
+
+## 本 Demo 演示一行文字的用法
+```
+
+## 插件配置
+
+`@ice/pkg-plugin-docusaurus` 插件接受以下配置：
+
+#### enable
+
+- 类型：`boolean | { start: boolean; build: boolean }`
+- 默认值：`true`
+
+是否启用文档预览构建。
+
+#### title
+
+- 类型：`string`
+- 默认值：`'ICE PKG'`
+
+配置文档标题。
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        title: 'My Docs',
+      },
+    ],
+  ],
+});
+```
+
+#### url
+
+- 类型：`string`
+- 默认值：`'/'`
+
+文档部署域名。比如部署在 github，则是 `https://your-repo.github.io`。
+
+#### baseUrl
+
+- 类型：`string`
+- 默认值：`'/'`
+
+文档路由的基准路由。比如如果配置了 `/metro`，则文档的基准地址是 `https://your-repo.github.io/metro`
+
+#### favicon
+
+- 类型：`string`
+- 默认值：`'https://img.alicdn.com/imgextra/i2/O1CN01jUf9ZP1aKwVvEc58W_!!6000000003312-73-tps-160-160.ico'`
+
+文档站点的 favicon 的地址。可以是相对部署根目录的路径，比如 `static/img/favicon.ico`。
+
+#### navBarLogo
+
+- 类型：`string`
+- 默认值：`'https://img.alicdn.com/imgextra/i1/O1CN01lZTSIX1j7xpjIQ3fJ_!!6000000004502-2-tps-160-160.png'`
+
+侧边栏的 logo。可以是相对部署根目录的路径，比如 `static/img/logo.png`。
+
+#### navBarTitle
+
+- 类型：`string`
+- 默认值：`'ICE PKG'`
+
+侧边栏标题。
+
+#### host
+
+- 类型：`string`
+- 默认值：本机 IP
+
+文档本地预览服务启动的 Host。
+
+#### port
+
+- 类型：`number`
+- 默认值：`4000`
+
+文档本地预览服务启动的端口号。
+
+#### sidebarItemsGenerator
+
+- 类型：`SidebarGenerator`
+
+自定义 sidebar 内容，详细说明见 [Docusaurus 文档](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#sidebarItemsGenerator)。
+
+#### mobilePreview
+
+- 类型：`boolean`
+- 默认值：`false`
+
+开启移动端组件预览模式。
+
+#### defaultLocale
+
+- 类型：`string`
+- 默认值：`'zh-Hans'`
+
+文档默认语言。
+
+#### locales
+
+- 类型：`string[]`
+- 默认值：`['zh-Hans']`
+
+文档需要构建的多语言版本。必须包含 defaultLocale。
+
+#### outputDir
+
+- 类型：`string`
+- 默认值：`'build'`
+
+配置 Docusaurus 构建产物输出地址。
+
+#### path
+
+- 类型：`string`
+- 默认值：`'docs'`
+
+存放文档的目录，将会扫描该目录下所有的 `.md` 和 `.mdx` 文件并生成文档页面。相关规则说明详见[文档](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#path)。
+
+#### docsRouteBasePath
+
+- 类型：`string`
+- 默认值：`'/'`
+
+文档基准路由，类似于 React Router 中的 `basename`，配置时需要注意的是首个字符不能是 `/`。比如以下的目录结构对应的页面路由如下：
+
+| 页面路径         | 路由     |
+| ---------------- | -------- |
+| `/docs/index.md` | `/`      |
+| `/docs/usage.md` | `/usage` |
+
+#### pagePath
+
+- 类型：`string`
+- 默认值：`'pages'`
+
+存放页面的目录，该目录下的组件将会自动生成为页面，一个组件的文件路径会被映射生成对应的路由。页面路由规则详见[文档](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-pages#path)。
+
+#### pageRouteBasePath
+
+- 类型：`string`
+- 默认值：`'/pages'`
+
+页面基准路由，类似于 React Router 中的 `basename`。比如以下的目录结构对应的页面路由如下：
+
+| 页面路径           | 路由          |
+| ------------------ | ------------- |
+| `/pages/index.tsx` | `/pages`      |
+| `/pages/home.tsx`  | `/pages/home` |
+
+#### plugins
+
+添加额外的 [Docusaurus 插件](https://docusaurus.io/docs/api/plugin-methods)，以扩展更多 Docusaurus 的能力。
+
+<Tabs>
+
+<TabItem value="build.config.mts" label="build.config.mts">
+
+```ts title="build.config.mts"
+import { defineConfig } from '@ice/pkg';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+export default defineConfig({
+  plugins: [
+    [
+      '@ice/pkg-plugin-docusaurus',
+      {
+        plugins: [
+          // 添加本地的 docusaurus 插件
+          require.resolve('./docusaurus-plugin.js'),
+          // 你也可以添加插件包
+          '@docusaurus/plugin-pwa',
+        ],
+      },
+    ],
+  ],
+});
+```
+
+</TabItem>
+
+<TabItem value="docusaurus-plugin.js" label="docusaurus-plugin.js">
+
+```js
+module.exports = function (context, options) {
+  return {
+    name: 'docusaurus-plugin',
+    async contentLoaded({ content, actions }) {
+      console.log(content);
+    },
+  };
+};
+```
+
+</TabItem>
+</Tabs>
diff --git a/website/docs/guide/publish.md b/website/versioned_docs/version-v1/guide/publish.md
similarity index 96%
rename from website/docs/guide/publish.md
rename to website/versioned_docs/version-v1/guide/publish.md
index e43a42f7..366eb235 100644
--- a/website/docs/guide/publish.md
+++ b/website/versioned_docs/version-v1/guide/publish.md
@@ -88,7 +88,7 @@ export { default as Input } from './Input';
 console.log(123);
 
 export default function Button() {
-  return (<button>Click Me</button>)
+  return <button>Click Me</button>;
 }
 ```
 
@@ -99,7 +99,7 @@ export default function Button() {
 console.log(123);
 
 export default function Input() {
-  return (<input />)
+  return <input />;
 }
 ```
 
@@ -135,11 +135,7 @@ import 'index.scss';
 
 ```json
 {
-  "sideEffects": [
-    "./esm/Input/index.js",
-    "*.css",
-    "*.less"
-  ]
+  "sideEffects": ["./esm/Input/index.js", "*.css", "*.less"]
 }
 ```
 
@@ -162,7 +158,6 @@ $ npm version minor
 
 关于 `npm-version` 的更多用法可以参考 [NPM 文档](https://docs.npmjs.com/cli/v9/commands/npm-version?v=true)。
 
-
 ## 构建和发布
 
 ICE PKG 的脚手架默认把构建命令配置在 `prepublishOnly`：
diff --git a/website/docs/guide/scenarios.md b/website/versioned_docs/version-v1/guide/scenarios.md
similarity index 87%
rename from website/docs/guide/scenarios.md
rename to website/versioned_docs/version-v1/guide/scenarios.md
index cdd5f631..43548bab 100644
--- a/website/docs/guide/scenarios.md
+++ b/website/versioned_docs/version-v1/guide/scenarios.md
@@ -15,7 +15,7 @@ $ npm init @ice/pkg my-lib
 ? 请选择项目类型 (Use arrow keys)
 ❯ React 组件
   Node 模块
-  前端类库  
+  前端类库
   Rax 组件
 ```
 
@@ -27,9 +27,9 @@ $ npm init @ice/pkg my-lib
 
 ```md
 src
-├── Header        # 子组件 Header
-|  ├── index.css
-|  └── index.tsx
+├── Header # 子组件 Header
+| ├── index.css
+| └── index.tsx
 └── index.tsx
 ```
 
@@ -46,7 +46,7 @@ export default function Component() {
       <Header />
       ...
     </div>
-  )
+  );
 }
 ```
 
@@ -58,7 +58,7 @@ export default function Component() {
 import './index.css';
 
 export default function Header() {
-  return (<div>Header</div>)
+  return <div>Header</div>;
 }
 ```
 
@@ -72,13 +72,14 @@ export default function Header() {
 ```md
 src
 ├── Button
-|  ├── index.css
-|  └── index.tsx
+| ├── index.css
+| └── index.tsx
 ├── Input
-|  ├── index.css
-|  └── index.tsx
+| ├── index.css
+| └── index.tsx
 └── index.ts
 ```
+
 <Tabs>
 <TabItem value="index.ts" label="index.ts">
 
@@ -95,9 +96,7 @@ export * from './Input';
 import * as React from 'react';
 
 export function Button() {
-  return (
-    <button>example</button>
-  )
+  return <button>example</button>;
 }
 ```
 
@@ -126,16 +125,17 @@ export function writeLicenseToFileHeader(absFilePath: string) {
 前端类库指的是运行在浏览器环境中的 JavaScript 模块，并且所有的依赖都会打包到这个模块里面。使用的场景有：
 
 1. 类似 [React](https://unpkg.com/browse/react@18.2.0/umd/)、[moment](https://unpkg.com/browse/moment@2.29.4/min/) 等类库，用户的项目中把这些依赖 external 掉，需要在 HTML 中通过 `<script />` 引入 UMD 产物：
+
 ```html
 <html>
-<head>
-  <script src="https://unpkg.com/your-lib-name/dist/index.umd.es5.production.js"></script>
-</head>
-<body>
-  <script>
-    console.log(window.YourLibName);
-  </script>
-</body>
+  <head>
+    <script src="https://unpkg.com/your-lib-name/dist/index.umd.es5.production.js"></script>
+  </head>
+  <body>
+    <script>
+      console.log(window.YourLibName);
+    </script>
+  </body>
 </html>
 ```
 
@@ -160,10 +160,7 @@ import { createElement } from 'rax';
 import styles from './index.module.css';
 
 export default function Component() {
-
-  return (
-    <div className={styles.Component}>Hello</div>
-  );
+  return <div className={styles.Component}>Hello</div>;
 }
 ```
 
diff --git a/website/versioned_docs/version-v1/guide/test.md b/website/versioned_docs/version-v1/guide/test.md
new file mode 100644
index 00000000..a6cac861
--- /dev/null
+++ b/website/versioned_docs/version-v1/guide/test.md
@@ -0,0 +1,257 @@
+# 测试
+
+<details open>
+  <summary>示例</summary>
+  <ul>
+    <li>
+      <a href="https://github.com/ice-lab/icepkg/tree/main/examples/react-component" target="_blank" rel="noopener noreferrer">
+        react-component
+      </a>
+    </li>
+    <li>
+      <a href="https://github.com/ice-lab/icepkg/tree/main/examples/rax-component" target="_blank" rel="noopener noreferrer">
+        rax-component
+      </a>
+    </li>
+  </ul>
+</details>
+
+ICE PKG 不耦合任意一个测试框架，开发者可自由选择。目前提供开箱即用 [Jest](https://jestjs.io/) 和 [Vitest](https://vitest.dev/) 配置，以便快速开始单元测试。
+
+## Jest
+
+### 安装依赖
+
+```bash
+$ npm i jest ts-jest -D
+```
+
+### 配置
+
+首先需要在项目的根目录下新建 `jest.config.mjs` 文件，并加入以下内容：
+
+```js
+import pkgService, { defineJestConfig } from '@ice/pkg';
+
+export default defineJestConfig(pkgService, {
+  // 你也可以使用 @swc/jest 编译 TS 代码
+  preset: 'ts-jest',
+});
+```
+
+`defineJestConfig()` 方法返回的是 ice.js 默认配置好的 Jest 配置，支持在第二个参数中传入自定义的 [Jest 配置](https://jestjs.io/docs/configuration)，第二个参数的类型是：
+
+```ts
+type UserJestConfig = jest.Config | () => Promise<jest.Config>
+```
+
+以添加 `@swc/jest` 为例：
+
+```js title="jest.config.mjs"
+import pkgService, { defineJestConfig } from '@ice/pkg';
+
+export default defineJestConfig(pkgService, {
+  transform: {
+    '^.+\\.(t|j)sx?$': [
+      '@swc/jest',
+      {
+        jsc: {
+          transform: {
+            react: {
+              runtime: 'automatic',
+            },
+          },
+        },
+      },
+    ],
+  },
+});
+```
+
+然后在 `package.json` 中加入 `test` 脚本：
+
+```diff
+{
+  "scripts": {
++   "test": "jest"
+  }
+}
+```
+
+### 编写测试用例
+
+#### 非 UI 测试
+
+假设现在要测试 `add()` 函数如下：
+
+```ts title="src/utils/add.ts"
+export default function add(a, b) {
+  return a + b;
+}
+```
+
+新建一个测试用例：
+
+```ts title="tests/add.spec.ts"
+import add from '../src/add';
+
+test('add function', () => {
+  expect(add(1, 2)).toBe(3);
+});
+```
+
+这时，运行 `npm run test` 查看测试结果了。
+
+#### UI 测试
+
+组件 UI 测试推荐使用 [@testing-library/react](https://www.npmjs.com/package/@testing-library/react) 和 [@testing-library/jest-dom](https://www.npmjs.com/package/@testing-library/jest-dom)。
+
+首先安装依赖：
+
+```bash
+$ npm i @testing-library/react jest-environment-jsdom @testing-library/jest-dom -D
+```
+
+然后在项目根目录下新建 `jest-setup.ts` 并写入以下内容，以扩展匹配器(matchers)：
+
+```ts title="jest-setup.ts"
+import '@testing-library/jest-dom';
+```
+
+最后在 `jest.config.mjs` 中加入以下内容：
+
+```diff title="jest.config.mjs"
+import pkgService, { defineJestConfig } from '@ice/pkg';
+
+export default defineJestConfig(pkgService, {
++ setupFilesAfterEnv: ['<rootDir>/jest-setup.ts'],
++ testEnvironment: 'jest-environment-jsdom',
+});
+```
+
+假设现在要测试一个 Header 组件：
+
+```tsx title="src/components/Header.tsx"
+export default function Header() {
+  return <h2 data-testid="title">Jest Test</h2>;
+}
+```
+
+编写组件的测试用例：
+
+```tsx title="tests/Header.spec.tsx"
+import { render, screen } from '@testing-library/react';
+import Header from '../src/components/Header';
+
+test('test Header component', () => {
+  render(<Header />);
+  expect(screen.getByTestId('title')).toHaveTextContent('Jest Test');
+});
+```
+
+最后，运行 `npm run test` 就可以查看测试结果了。
+
+## Vitest
+
+### 安装依赖
+
+```bash
+$ npm i vitest -D
+```
+
+### 配置
+
+首先需要在项目的根目录下新建 `vitest.config.mts` 文件，并加入以下内容：
+
+```js title="vitest.config.mts"
+import pkgService, { defineVitestConfig } from '@ice/pkg';
+
+export default defineVitestConfig(pkgService, {});
+```
+
+`defineVitestConfig()` 方法返回的是 ice.js 默认配置好的 vitest 配置，支持传入自定义的 [vitest 配置](https://vitest.dev/config/)。
+
+defineVitestConfig 第二个入参支持以下三种类型：
+
+- `vitest.UserConfig`
+- `Promise<vitest.UserConfig>`
+- `(env) => Promise<vitest.UserConfig>`
+
+以修改 `include` 参数为例：
+
+```diff title="vitest.config.mts"
+import pkgService, { defineVitestConfig } from '@ice/pkg';
+
+export default defineVitestConfig(pkgService, {
++ test: {
++   include: ['**/*.{test,spec}.{js,mjs,cjs,ts,mts,cts,jsx,tsx}']
++ }
+});
+```
+
+然后在 `package.json` 中加入 `test` 脚本：
+
+```diff title="package.json"
+{
+  "scripts": {
++   "test": "vitest"
+  }
+}
+```
+
+### 编写测试用例
+
+#### 非 UI 测试
+
+请见 [Jest 非 UI 测试章节](#非-ui-测试)。
+
+首先安装依赖：
+
+```bash
+$ npm i @testing-library/react jsdom @testing-library/jest-dom -D
+```
+
+然后在项目根目录下新建 `vitest-setup.ts` 并写入以下内容，以扩展匹配器(matchers)：
+
+```ts title="vitest-setup.ts"
+import matchers from '@testing-library/jest-dom/matchers';
+import { expect } from 'vitest';
+
+expect.extend(matchers);
+```
+
+最后在 `vitest.config.mts` 中加入以下内容：
+
+```diff title="vitest.config.mts"
+import pkgService, { defineVitestConfig } from '@ice/pkg';
+
+export default defineVitestConfig(pkgService, {
++ test: {
++   environment: 'jsdom',
++   setupFiles: ['./vitest-setup.ts'],
++ },
+});
+```
+
+假设现在测试一个 Header 组件：
+
+```tsx title="src/components/Header.tsx"
+export default function Header() {
+  return <h2 data-testid="title">Vitest Test</h2>;
+}
+```
+
+编写组件的测试用例：
+
+```tsx title="tests/Header.spec.tsx"
+import { test, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import Header from '../src/components/Header';
+
+test('test Header component', () => {
+  render(<Header />);
+  expect(screen.getByTestId('title')).toHaveTextContent('Vitest Test');
+});
+```
+
+最后，运行 `npm run test` 就可以查看测试结果了。
diff --git a/website/versioned_docs/version-v1/index.md b/website/versioned_docs/version-v1/index.md
new file mode 100644
index 00000000..b1d3beb5
--- /dev/null
+++ b/website/versioned_docs/version-v1/index.md
@@ -0,0 +1,52 @@
+# ICE PKG
+
+ICE PKG 是飞冰开源的 NPM 包开发解决方案，默认支持 React 组件、Rax 组件、Node 模块、前端类库等多场景 NPM 包的研发。
+
+## 特性
+
+- **📈 更快**：使用 [SWC](https://swc.rs/docs/configuration/swcrc) 编译和压缩，提升数十倍编译速度
+- **🎊 双模式**：同时提供 Transform + Bundle 两种构建模式
+- **🅾️ 零配置**：无需任何配置，提供内建的 TypeScript、JSX 等构建支持
+- **☄️ 面向未来**：提供 ES2017 产物，打包出面向现代浏览器支持的产物
+- **☘️ 文档预览**：基于 [Docusaurus](https://docusaurus.io/) 提供预览文档、生成静态文档能力
+
+### 更快
+
+使用 SWC 与 [tsc](https://www.typescriptlang.org/)、[Babel](https://babeljs.io/) 编译同一个项目之间耗时对比：
+
+<figure style={{
+  maxWidth: '800px',
+  fontSize: '13px',
+  lineHeight: '20px'
+}}>
+  <img src="https://img.alicdn.com/imgextra/i1/O1CN01MoY2ji23DGjyTw2Dh_!!6000000007221-2-tps-2972-638.png" alt="benchmark" />
+
+<figcaption>Above: benchmark 使用 <a href="https://github.com/maoxiaoke/pkg-benchmark">飞冰 fusion pro</a> 模板</figcaption>
+</figure>
+
+### 双模式
+
+社区的众多方案如 [Microbundle](https://github.com/developit/microbundle)、[tsup](https://github.com/egoist/tsup) 均只支持打包模式 (将所有依赖文件打包成一个文件输出，下称 Bundle 模式)。但 Bundle 模式[并非总是最佳选择](https://github.com/ice-lab/icepkg/issues/301)。其中最为**显著的问题**在于：**对 Tree-Shaking 不友好**，无用的依赖总是会被打包到最终的输出产物中，继而影响应用的体积。
+
+ICE PKG 除支持 Bundle 模式外，也默认支持了 Transform 模式（将文件挨个编译到输出目录）。更多内容请参考[构建能力 — 双模式构建](./guide/abilities#双模式构建)。
+
+### ES2017 产物
+
+为现代浏览器提供 ES2017 产物，可以减少产物体积，亦可加快执行速度。更多内容参考 [构建能力 — es2017 产物](./guide/abilities#es2017-产物)。
+
+### 多场景
+
+依赖 ICE PKG 强大的[双模式](#双模式)能力，支持多类场景的开发需求。包括但不限定于以下场景：
+
+- React 组件
+- Rax 组件
+- Node 模块
+- 前端类库
+
+### 文档预览
+
+结合 [Docusaurus](https://docusaurus.io/)，ICE PKG 升级了文档预览的能力。更多内容参考 [指南 - 文档预览](./guide/preview)。
+
+## 社区
+
+如果你有疑问或者需要帮助，可以通过 [GitHub Issues](https://github.com/ice-lab/icepkg/issues) 来寻求帮助。
diff --git a/website/versioned_docs/version-v1/quick-start.md b/website/versioned_docs/version-v1/quick-start.md
new file mode 100644
index 00000000..7bcb7b2c
--- /dev/null
+++ b/website/versioned_docs/version-v1/quick-start.md
@@ -0,0 +1,74 @@
+# 快速开始
+
+## 环境准备
+
+### 1. Node.js
+
+使用 ICE PKG 开发前需要安装 [Node.js](https://nodejs.org)，并确保 node 版本是 16.14 或以上。
+
+### 2. 包管理工具
+
+安装 Node.js 后，默认会包含 npm。在国内使用 npm 安装依赖可能会比较慢。建议使用 [cnpm](https://www.npmjs.com/package/cnpm) 的国内镜像源进行加速：
+
+```bash
+$ npm install -g cnpm --registry=https://registry.npmmirror.com
+# 验证 cnpm 安装是否成功
+$ cnpm -v
+```
+
+除此之外，你还可以使用 [pnpm](https://pnpm.io/)、[yarn](https://yarnpkg.com/) 等其他包管理工具。本文档仍以 npm 作为示例。
+
+## 初始化
+
+以 React 组件类型为例，通过以下命令，可以快速初始化一个项目：
+
+```bash
+$ npm init @ice/pkg@latest react-component
+```
+
+选择 React 组件项目类型：
+
+```bash
+? 请选择项目类型 (Use arrow keys)
+❯ React 组件
+  Node 模块
+  前端类库
+  Rax 组件
+```
+
+你还可以通过附加的命令行选项的方式指定你想要的模板和 npm 包名，比如：
+
+```bash
+$ npm init @ice/pkg@latest react-component --template @ice/template-pkg-react --npmName my-react-component
+```
+
+## 启动项目
+
+```bash
+$ cd react-component
+$ npm start
+```
+
+现在，访问 `http://localhost:4000`，即可查看组件 README 文档：
+
+![demo-readme](https://img.alicdn.com/imgextra/i2/O1CN01OctOw81JXuHCC6FhP_!!6000000001039-2-tps-1110-720.png)
+
+访问 `http://localhost:4000/usage`，即可预览组件：
+
+![component-preview](https://img.alicdn.com/imgextra/i3/O1CN01uEHuWp1DtXHv6uwax_!!6000000000274-2-tps-1160-540.png)
+
+## 生成构建产物
+
+```shell
+$ npm run build
+```
+
+## 发布产物
+
+1. 在 `package.json` 中修改包名
+
+2. 执行发布命令：
+
+```bash
+$ npm publish
+```
diff --git a/website/versioned_docs/version-v1/reference/cli.md b/website/versioned_docs/version-v1/reference/cli.md
new file mode 100644
index 00000000..68e8357a
--- /dev/null
+++ b/website/versioned_docs/version-v1/reference/cli.md
@@ -0,0 +1,29 @@
+# CLI
+
+## start
+
+启动本地调试服务。
+
+```bash
+$ ice-pkg start [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |
+
+## build
+
+执行编译或者打包构建，输出构建产物。
+
+```bash
+$ ice-pkg build [options]
+```
+
+|         选项          |   类型    | 说明                          |
+| :-------------------: | :-------: | ----------------------------- |
+|  `--config <config>`  | `string`  | 指定配置文件路径              |
+| `--rootDir <rootDir>` | `string`  | 指定应用运行的根目录          |
+|     `--analyzer`      | `boolean` | Bundle 模式下开启体积构建分析 |
diff --git a/website/docs/reference/config.md b/website/versioned_docs/version-v1/reference/config.md
similarity index 84%
rename from website/docs/reference/config.md
rename to website/versioned_docs/version-v1/reference/config.md
index 97795171..fe051049 100644
--- a/website/docs/reference/config.md
+++ b/website/versioned_docs/version-v1/reference/config.md
@@ -78,7 +78,7 @@ export default defineConfig({
 ### define
 
 - 类型：`Record<string, string | boolean | number | object | null>`
-- 默认值：`{ __DEV__: 'true' | 'false', 'process.env.NODE_ENV': '"development"' | '"production"', 'import.meta.vitest': 'undefined' }`
+- 默认值：`{ __DEV__: 'true' | 'false', 'process.env.NODE_ENV': '"development"' | '"production"' }`
 
 定义编译时环境变量，会在编译时被替换。注意：属性值会经过一次 `JSON.stringify()` 转换。
 
@@ -119,8 +119,6 @@ if (__DEV__) {
 实际上，在编译时，`__DEV__` 会被替换为 `process.env.NODE_ENV !== 'production'`。
 :::
 
-另外，ICE PKG 默认会将 `import.meta.vitest` 替换为 `undefined`。这意味着在源码里使用 Vitest 的 [in-source test](https://vitest.dev/guide/in-source.html) 写法时，非测试构建默认不会把对应测试逻辑保留到产物中。
-
 ### sourceMaps
 
 - 类型：`boolean | 'inline'`
@@ -264,61 +262,18 @@ export default defineConfig({
 - es2017 # ES module + ES2017 产物
 ```
 
-#### entryRoot
-
-- 类型：`string`
-- 默认值：自动推导（已配置 entry 父目录的最近公共祖先）
-
-用于控制 Transform 模式输出路径的相对根目录。该配置只影响产物路径映射，不影响文件处理范围。
-
-例如，当 entry 是 `./src/a/b/c/index.ts`：
-
-- `entryRoot: './src/a/b'` 时，输出为 `esm/c/index.js`
-- `entryRoot: './src'` 时，输出为 `esm/a/b/c/index.js`
-
-```ts title="build.config.mts"
-import { defineConfig } from '@ice/pkg';
-
-export default defineConfig({
-  entry: './src/a/b/c/index.ts',
-  transform: {
-    formats: ['esm'],
-    entryRoot: './src/a/b',
-  },
-});
-```
-
-当使用 `pkgs` 配置时，`pkgs[].entryRoot` 的优先级高于 `transform.entryRoot`。
-
-```ts title="build.config.mts"
-import { defineConfig } from '@ice/pkg';
-
-export default defineConfig({
-  transform: {
-    entryRoot: './src',
-  },
-  pkgs: [
-    {
-      id: 'button',
-      entry: './src/components/button/index.ts',
-      entryRoot: './src/components',
-    },
-  ],
-});
-```
-
 #### excludes
 
 - 类型：`string | string[]`
-- 默认值：`['**/__tests__/**']`
+- 默认值：`undefined`
 
-排除无需编译的文件。默认会排除 `__tests__` 目录下文件。比如，我们还不想编译 `src` 下以 `*.test.[j|t]s` 结尾的测试文件。
+排除无需编译的文件。比如，我们不想编译 `src` 下的所有测试文件，其中测试文件包含在 `__tests__` 目录下，或以 `*.test.[j|t]s` 结尾。
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
 
 export default defineConfig({
-  transform: {
+  transfrom: {
     excludes: ['**/__tests__/**', '*.test.[j|t]s'],
   },
 });
@@ -419,12 +374,10 @@ export default defineConfig({
 
 #### externals
 
-- 类型：`boolean | Record<string, string> | (string | RegExp | Record<string, string>)[]`
-- 默认值：`false`
+- 类型：`boolean | Record<string, string>`
+- 默认值：`true`
 
-默认情况下，bundle 的产物包含所有依赖产物。该选项可修改这一结果。
-若想要 Bundle 不包含依赖产物，可以传入 `true`，其会解析 `package.json` 并将所有依赖 external 掉，包括 node 的依赖。
-适合针对 Node 环境的构建。
+默认情况下，bundle 的产物包含所有依赖产物。该选项可修改这一结果。若想要 Bundle 不包含依赖产物，可如下配置：
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
@@ -436,18 +389,7 @@ export default defineConfig({
 });
 ```
 
-若想要自定义配置 externals，则可以直接传入想要 external 的依赖，支持字符串和正则表达式。
-
-```ts title="build.config.mts"
-import { defineConfig } from '@ice/pkg';
-export default defineConfig({
-  bundle: {
-    externals: ['react', 'react-dom', /^@ice($|\/)/],
-  },
-});
-```
-
-如果你选择构建 umd 格式，默认情况下会根据一定的规则生成从全局对象上获取依赖的名字，如果你想自定义，则可以直接传入一个对象来配置。
+若想要自定义配置 externals，参考如下配置：
 
 ```ts title="build.config.mts"
 import { defineConfig } from '@ice/pkg';
@@ -462,8 +404,6 @@ export default defineConfig({
 });
 ```
 
-当然，也可以进行混合使用。
-
 #### minify
 
 - 类型：`boolean | { js?: boolean | ((mode: string, command: string) => boolean | { options?: swc.JsMinifyOptions }); css?: boolean | ((mode: string, command: string) => boolean | { options?: cssnano.Options });}`
diff --git a/website/docs/reference/plugins-development.md b/website/versioned_docs/version-v1/reference/plugins-development.md
similarity index 87%
rename from website/docs/reference/plugins-development.md
rename to website/versioned_docs/version-v1/reference/plugins-development.md
index 148cb7a9..37299a4a 100644
--- a/website/docs/reference/plugins-development.md
+++ b/website/versioned_docs/version-v1/reference/plugins-development.md
@@ -496,19 +496,19 @@ ICE PKG 插件提供以下生命周期钩子：
 
 - build 命令：
 
-| 生命周期            | 参数                                                                                                                                       | 调用时机           |
-| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ |
-| before.build.load   | `{ args: CommandArgs; config: PkgConfig[] }`                                                                                               | 获取所有任务配置后 |
-| before.build.run    | `{ args: CommandArgs; config: PkgConfig[] }`                                                                                               | 编译执行之前       |
-| after.build.compile | `{ taskName: string; outputFiles: OutputFile[]; outputs?: Array<rollup.RollupOutput['output']>; modules?: rollup.RollupCache['modules'] }` | 编译结束           |
+| 生命周期            | 参数   | 调用时机           |
+| :------------------ | :----- | :----------------- |
+| before.build.load   | Object | 获取所有任务配置后 |
+| before.build.run    | Object | 编译执行之前       |
+| after.build.compile | Object | 编译结束           |
 
 - start 命令
 
-| 生命周期            | 参数                                                                             | 调用时机           |
-| ------------------- | -------------------------------------------------------------------------------- | ------------------ |
-| before.start.load   | `{ args: CommandArgs; config: PkgConfig[] }`                                     | 获取所有任务配置后 |
-| before.start.run    | `{ args: CommandArgs; config: PkgConfig[]  }`                                    | 编译执行之前       |
-| after.start.compile | `{ taskName: string; outputFiles: OutputFile[]; modules?: rollup.ModuleJSON[] }` | 编译结束           |
+| 生命周期            | 参数   | 调用时机           |
+| :------------------ | :----- | :----------------- |
+| before.start.load   | Object | 获取所有任务配置后 |
+| before.start.run    | Object | 编译执行之前       |
+| after.start.compile | Object | 编译结束           |
 
 ### registerTask
 
diff --git a/website/versioned_sidebars/version-v1-sidebars.json b/website/versioned_sidebars/version-v1-sidebars.json
new file mode 100644
index 00000000..0f90a0e5
--- /dev/null
+++ b/website/versioned_sidebars/version-v1-sidebars.json
@@ -0,0 +1,24 @@
+{
+  "tutorialSidebar": [
+    { "type": "doc", "id": "index" },
+    { "type": "doc", "id": "quick-start" },
+    { "type": "doc", "id": "guide/abilities" },
+    { "type": "doc", "id": "guide/scenarios" },
+    { "type": "doc", "id": "guide/build" },
+    { "type": "doc", "id": "guide/publish" },
+    { "type": "doc", "id": "guide/test" },
+    { "type": "doc", "id": "guide/preview" },
+    { "type": "doc", "id": "guide/jsx-plus" },
+    { "type": "doc", "id": "guide/monorepo" },
+    {
+      "type": "category",
+      "label": "参考",
+      "items": [
+        { "type": "doc", "id": "reference/cli" },
+        { "type": "doc", "id": "reference/config" },
+        { "type": "doc", "id": "reference/plugins-development" }
+      ]
+    },
+    { "type": "doc", "id": "faq", "label": "常见问题" }
+  ]
+}
diff --git a/website/versions.json b/website/versions.json
new file mode 100644
index 00000000..868a38e3
--- /dev/null
+++ b/website/versions.json
@@ -0,0 +1 @@
+["v1"]