diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9074220e8..54cbace165 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,10 @@
+# v3.0.22-cpp
+
+`2026-08-28`
+
+- 🐛 fix(swipe): 修复 Taro Android/iOS 环境下 `document.addEventListener` 不是函数导致报错的问题
+- 🐛 fix(taro): 修复 imagepreview/barrage/popover 在 Taro 非 H5 环境下访问 `document` API 报错的问题
+
# v3.0.21-cpp
`2026-05-20`
diff --git a/package.json b/package.json
index 058a4356fa..db1d8d969b 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "@nutui/nutui-react-taro",
- "version": "3.0.21-cpp",
+ "version": "3.0.22-cpp",
"style": "dist/style.css",
"main": "dist/nutui.react.umd.js",
"module": "dist/es/packages/nutui.react.build.js",
diff --git a/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap b/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap
index 86979e3e48..fa51247148 100644
--- a/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap
+++ b/src/packages/address/__test__/__snapshots__/address.spec.tsx.snap
@@ -1,15 +1,15 @@
// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
-exports[`Address: exist defaultIcon & selectIcon 1`] = `"
"`;
+exports[`Address: exist defaultIcon & selectIcon 1`] = `""`;
-exports[`Address: show cascader false 1`] = `""`;
+exports[`Address: show cascader false 1`] = `""`;
-exports[`Address: show custom icon 1`] = `""`;
+exports[`Address: show custom icon 1`] = `""`;
-exports[`Address: show custom icon 2`] = `""`;
+exports[`Address: show custom icon 2`] = `""`;
-exports[`Address: show custom true 1`] = `""`;
+exports[`Address: show custom true 1`] = `""`;
-exports[`Address: show elevator 1`] = `""`;
+exports[`Address: show elevator 1`] = `""`;
-exports[`Address: show exist 1`] = `""`;
+exports[`Address: show exist 1`] = `""`;
diff --git a/src/packages/barrage/__tests__/barrage.spec.tsx b/src/packages/barrage/__tests__/barrage.spec.tsx
index 809d5d647e..41d2b79ab9 100644
--- a/src/packages/barrage/__tests__/barrage.spec.tsx
+++ b/src/packages/barrage/__tests__/barrage.spec.tsx
@@ -88,3 +88,25 @@ test('should danmu rows top', async () => {
{ timeout: 4000 }
)
})
+
+describe('barrage.taro document guard logic', () => {
+ test('skips createElement when document.createElement is not a function', () => {
+ const original = document.createElement.bind(document)
+ // @ts-expect-error simulate non-H5 Taro env
+ document.createElement = undefined
+
+ const shouldSkip =
+ typeof document === 'undefined' ||
+ typeof document.createElement !== 'function'
+ expect(shouldSkip).toBe(true)
+
+ document.createElement = original
+ })
+
+ test('does not skip createElement in normal H5 env', () => {
+ const shouldSkip =
+ typeof document === 'undefined' ||
+ typeof document.createElement !== 'function'
+ expect(shouldSkip).toBe(false)
+ })
+})
diff --git a/src/packages/barrage/barrage.taro.tsx b/src/packages/barrage/barrage.taro.tsx
index f5e2e6c254..7851a5b3e1 100644
--- a/src/packages/barrage/barrage.taro.tsx
+++ b/src/packages/barrage/barrage.taro.tsx
@@ -144,6 +144,11 @@ const InternalBarrage: ForwardRefRenderFunction<
if (!loop && index.current >= list.length) {
return
}
+ if (
+ typeof document === 'undefined' ||
+ typeof document.createElement !== 'function'
+ )
+ return
const _index = loop ? index.current % list.length : index.current
const el = document.createElement(`View`)
diff --git a/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap b/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap
index 5f66a078d4..2f3e8d0f68 100644
--- a/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap
+++ b/src/packages/cascader/__tests__/__snapshots__/cascader.spec.tsx.snap
@@ -11,11 +11,13 @@ exports[`Cascader > value 1`] = ``;
exports[`Cascader > visible true 1`] = `