fix: 修复多平台运行读取不到 pages.json 的问题

[skiyee]

#32

Summary by CodeRabbit

发布说明

• 新增功能

  • 新增子包页面支持，可配置嵌套页面结构

• 更新

  • 更新项目依赖，引入页面解析工具
  • 完善构建配置，支持子包页面识别
  • 增强类型定义系统，提升开发体验

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

总体说明

此更改通过集成新的Vite插件和配置调整，引入了对Uni小程序子包支持。更新了依赖项，重构了页面JSON解析逻辑，并添加了TypeScript类型声明和新的页面组件文件。

变更内容

内容集 / 文件	变更摘要
NPM配置与依赖 .npmrc, package.json	添加新的npm registry配置行，更新package.json依赖：添加 @dcloudio/uni-cli-shared 版本3.0.0-4040520250104002，移除 jsonc-parser。
示例项目依赖 examples/package.json	添加开发依赖 @uni-helper/vite-plugin-uni-pages 版本^0.3.22。
构建配置 examples/vite.config.ts	导入并集成UniPages插件，传入subPackages配置 ['src/pages-sub'] 以支持嵌套子包。
页面配置 examples/pages.json	重构页面配置结构：为现有页面添加type字段，引入条件编译块（#ifdef H5），新增subPackages字段用于管理子包页面，调整导航栏样式定义。
类型声明 examples/uni-pages.d.ts	新建TypeScript声明文件，定义页面路由类型 _LocationUrl、导航选项接口（NavigateToOptions、RedirectToOptions、SwitchTabOptions）、ReLaunchOptions组合类型，以及扩展Uni命名空间的导航方法。
页面组件 examples/src/pages-sub/index.vue	新增Vue单文件组件，包含渲染"子包首页"文本的template模板。
核心工具 src/utils.ts	重构loadPagesJson函数，用专用的parseMiniProgramPagesJson解析器替代本地jsonc-parser逻辑，传入平台上下文和subpackages选项。

预估代码审查工作量

🎯 3 (中等) | ⏱️ ~20-25 分钟

需要特别关注的区域：

• examples/pages.json 中的条件编译块和子包配置结构变化，需验证与原有页面配置的兼容性
• examples/uni-pages.d.ts 中新增的类型定义是否准确对应生成的页面路由
• src/utils.ts 中解析逻辑重构，需确认新解析器与旧逻辑的功能等价性及平台参数正确传递
• examples/vite.config.ts 中subPackages路径配置与实际文件结构的一致性

诗歌

🐰 新的子包来敲门，
类型声明护航行，
页面结构焕然新，
解析器换人一身，
条件编译显威能！✨

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	You can run @coderabbitai generate docstrings to improve docstring coverage.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	PR 标题准确描述了主要变更：修复了多平台运行时读取 pages.json 的问题，与文件变更内容高度相关。

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[pkg-pr-new]

Open in StackBlitz

commit: 960c7c7

[coderabbitai]

Actionable comments posted: 3

🧹 Nitpick comments (1)

examples/uni-pages.d.ts (1)

17-19: 空接口可以优化

Biome 正确指出空接口等同于 {}。虽然这是生成的文件，但建议在 vite-plugin-uni-pages 插件中改进生成逻辑。

根据 Biome 的建议，可以改为：

-interface SwitchTabOptions {
-  
-}
+type SwitchTabOptions = Record<string, never>;

或者如果未来可能添加属性：

-interface SwitchTabOptions {
-  
-}
+interface SwitchTabOptions {
+  // Reserved for future use
+}

不过由于这是生成的文件，该改进应该在插件源码中实现，而不是手动修改此文件。

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fd36fe7 and 960c7c7.

⛔ Files ignored due to path filters (1)

• pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (8)

• .npmrc (1 hunks)
• examples/package.json (1 hunks)
• examples/src/pages-sub/index.vue (1 hunks)
• examples/src/pages.json (1 hunks)
• examples/uni-pages.d.ts (1 hunks)
• examples/vite.config.ts (2 hunks)
• package.json (1 hunks)
• src/utils.ts (2 hunks)

🧰 Additional context used

🪛 Biome (2.1.2)

examples/src/pages.json

[error] 3-3: Expected an array, an object, or a literal but instead found '// GENERATED BY UNI-PAGES, PLATFORM: H5 || MP-WEIXIN'.

Expected an array, an object, or a literal here.

(parse)

---

[error] 4-7: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 7-7: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 8-11: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 11-11: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 12-15: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 15-16: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 17-20: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 21-22: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 23-23: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 23-23: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 27-27: Expected an array, an object, or a literal but instead found '// GENERATED BY UNI-PAGES, PLATFORM: H5 || MP-WEIXIN'.

Expected an array, an object, or a literal here.

(parse)

---

[error] 23-26: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 27-27: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

---

[error] 28-31: End of file expected

Use an array for a sequence of values: [1, 2]

(parse)

examples/uni-pages.d.ts

[error] 16-19: An empty interface is equivalent to {}.

Safe fix: Use a type alias instead.

(lint/suspicious/noEmptyInterface)

🔇 Additional comments (10)

examples/src/pages.json (3)

16-21: 条件编译语法的正确使用

// #ifdef H5 和 // #endif 是 uni-app 的条件编译语法，用于平台特定的配置。这解释了为什么需要使用官方的 parseMiniProgramPagesJson 解析器而不是普通的 JSON 解析器。

Biome 报告的 JSON 语法错误是误报，因为 uni-app 的 pages.json 支持 JSONC 格式和条件编译注释。

建议在 Biome 配置中排除 pages.json 文件的检查：

{
  "linter": {
    "ignore": ["**/pages.json"]
  }
}

---

23-34: subPackages 配置正确实现了分包功能

新增的 subPackages 配置正确定义了 pages-sub 子包，这与：

• examples/vite.config.ts 中的 UniPages({ subPackages: ['src/pages-sub'] }) 配置一致
• examples/src/pages-sub/index.vue 子包页面相对应
• examples/uni-pages.d.ts 中的 "/pages-sub/index" 类型定义匹配

实现符合 uni-app 分包规范。

---

3-3: No action needed. The file examples/src/pages.json is a source configuration file required by the build process and should remain committed to version control. It does not contain auto-generated content markers and is not produced by any generation plugin.

examples/uni-pages.d.ts (2)

1-4: 生成的类型定义文件配置正确

禁用 ESLint、Prettier 和 TypeScript 检查对于生成的文件是正确的做法，避免了不必要的代码风格警告。

---

6-10: 类型定义正确反映了页面路由结构

_LocationUrl 联合类型准确地包含了所有页面路径：

• 主包页面：/pages/index, /pages/about, /pages/excluded
• 子包页面：/pages-sub/index

这与 pages.json 中的配置完全一致，提供了类型安全的路由跳转。

examples/src/pages-sub/index.vue (1)

1-3: 简洁的子包页面组件

这是一个用于演示分包功能的简单组件，内容足够用于测试 pages-sub 子包的加载和路由跳转功能。

examples/vite.config.ts (2)

4-4: 正确引入 UniPages 插件

引入 @uni-helper/vite-plugin-uni-pages 插件是实现 uni-app 分包功能的正确方式，该插件能够：

• 自动解析 pages.json 配置
• 生成类型定义文件（uni-pages.d.ts）
• 支持子包（subPackages）配置

---

13-15: Code snippet in review does not match actual file content

The review comment references a UniPages plugin configuration at lines 13-15 of examples/vite.config.ts, but the actual file contains UniKuRoot plugin configuration at those lines. The claimed plugin order (UniPlatform → UniPages → UniKuRoot → Uni) does not match the actual configuration (UniPlatform → UniKuRoot → Uni).

Additionally, examples/src/pages.json does not contain any subPackages configuration. The UniPages plugin is not referenced anywhere in the codebase.

Likely an incorrect or invalid review comment.

src/utils.ts (2)

29-31: Simplified parsing logic improves code quality

Using parseMiniProgramPagesJson instead of manual JSONC parsing is the correct approach for better handling of:

• Platform conditional compilation (// #ifdef, // #endif)
• Unified pages and subPackages parsing
• Various edge cases

The code logic is concise and clear. Verify that the parser correctly handles all page paths including subpackages by reviewing the function's return structure and testing with sample configurations containing subpackages.

---

27-27: Line number correction needed: Review points to line 27, but the actual code is at line 109

The concern about process.env.UNI_PLATFORM being undefined is valid in principle, but the current implementation includes a guard: normalizePlatformPath is only called when hasPlatformPlugin is true (line 89 in src/index.ts), and the plugin sets UNI_PLATFORM when detected.

However, adding a defensive default value is still reasonable for robustness:

-const platform = process.env.UNI_PLATFORM
+const platform = process.env.UNI_PLATFORM || 'h5'

This prevents potential edge cases where the guard logic might fail or the function is called unexpectedly, causing the string template to convert undefined to "undefined" and produce incorrect path matching.