{"id":46600577,"url":"https://github.com/uni-ku/pages-json","last_synced_at":"2026-04-16T07:02:44.374Z","repository":{"id":253271989,"uuid":"842996209","full_name":"uni-ku/pages-json","owner":"uni-ku","description":"使用 TypeScript / JavaScript 来编写 uni-app 的 pages.json","archived":false,"fork":false,"pushed_at":"2026-04-16T05:36:29.000Z","size":1027,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-04-16T06:40:52.100Z","etag":null,"topics":["pages","uni-app","uni-pages","uniapp","uniapp-cli"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uni-ku.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-08-15T14:56:52.000Z","updated_at":"2026-04-16T05:36:29.000Z","dependencies_parsed_at":"2026-01-19T06:04:59.408Z","dependency_job_id":null,"html_url":"https://github.com/uni-ku/pages-json","commit_stats":null,"previous_names":["uni-ku/define-page","uni-ku/pages-json"],"tags_count":60,"template":false,"template_full_name":null,"purl":"pkg:github/uni-ku/pages-json","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Fpages-json","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Fpages-json/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Fpages-json/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Fpages-json/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uni-ku","download_url":"https://codeload.github.com/uni-ku/pages-json/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uni-ku%2Fpages-json/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31875183,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pages","uni-app","uni-pages","uniapp","uniapp-cli"],"created_at":"2026-03-07T16:03:20.591Z","updated_at":"2026-04-16T07:02:44.364Z","avatar_url":"https://github.com/uni-ku.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @uni-ku/pages-json\n\n使用 TypeScript / JavaScript 动态生成 uni-app 的 pages.json 配置文件。\n\n## ✨ 特性\n\n- 🚀 **条件编译支持** - 根据平台动态生成配置\n- 🔧 **类型安全** - 完整的 TypeScript 类型提示和约束\n- 📝 **JavaScript 对象** - 支持 JS Object 配置方式\n- ⚡ **函数式编程** - 支持同步和异步函数生成配置\n- 🔗 **模块导入** - 支持从外部导入变量和函数\n- 🎯 **智能路径生成** - 自动根据文件路径生成页面路径\n\n## 📦 安装\n\n```shell\npnpm i -D @uni-ku/pages-json\n```\n\n## ⚙️ 配置\n\n### Vite 配置\n\n```ts\nimport uni from '@dcloudio/vite-plugin-uni';\nimport { hookUniPlatform } from '@uni-ku/pages-json/hooks';\nimport pagesJson from '@uni-ku/pages-json/vite';\nimport { defineConfig } from 'vite';\n\nexport default defineConfig({\n  plugins: [\n    pagesJson({\n      hooks: [hookUniPlatform], // 支持 vite-plugin-uni-platform\n    }),\n    uni(), // 必须放在 pagesJson() 之后\n  ],\n});\n```\n\n### 类型声明配置\n\n在 `tsconfig.json` 中添加类型声明：\n\n```json\n{\n  \"compilerOptions\": {\n    \"types\": [\"@uni-ku/pages-json/client\"]\n  }\n}\n```\n\n### 详细配置选项\n\n```ts\nexport interface UserConfig {\n  /**\n   * 项目根目录\n   * @default process.env.UNI_CLI_CONTEXT || process.cwd()\n   */\n  root?: string;\n\n  /**\n   * 源码目录\n   * @default process.env.UNI_INPUT_DIR || path.resolve(root, 'src') || root\n   */\n  src?: string;\n\n  /**\n   * 页面目录路径 （基于源码目录的相对路径 / 绝对路径）\n   * @default 'pages'\n   */\n  pageDir?: string;\n\n  /**\n   * 子包目录路径数组 （基于源码目录的相对路径 / 绝对路径）\n   * @default []\n   */\n  subPackageDirs?: string[];\n\n  /**\n   * 排除的文件模式\n   * @default ['node_modules', '.git', '** /__*__/ **']\n   */\n  exclude?: string[];\n\n  /**\n   * TS 声明文件路径  （基于源码目录的相对路径 / 绝对路径）\n   * false 则取消生成\n   * @default \"pages.d.ts\"\n   */\n  dts?: string | boolean;\n\n  /**\n   * 调试模式\n   * @default false\n   */\n  debug?: boolean | 'info' | 'error' | 'debug' | 'warn';\n\n  /**\n   * 钩子函数数组\n   */\n  hooks?: ConfigHook[];\n\n  /**\n   * 缓存目录\n   * @default 'node_modules/.cache/@uni-ku/pages-json'\n   */\n  cacheDir?: string;\n\n  /**\n   * 指定需要的平台，避免动态条件编译（方式一）造成的 pages.json 变动\n   */\n  platform?: BuiltInPlatform | BuiltInPlatform[];\n\n  /**\n   * pages.json 格式化缩进，默认使用 4 个空格缩进\n   */\n  indent?: string | number;\n}\n\nexport interface ConfigHook {\n  /**\n   * 获取页面路径\n   */\n  parsePageOption?: (opt: PageFileOption) =\u003e MaybePromise\u003cPageFileOption\u003e;\n\n  /**\n   * 过滤、修改 pages 的页面文件信息\n   */\n  filterPages?: (platform: UniPlatform, opts: PageFileOption[]) =\u003e MaybePromise\u003cPageFileOption[]\u003e;\n\n  /**\n   * 修改生成的页面配置\n   * 返回 null 可忽略该页面\n   */\n  transformPage?: (platform: UniPlatform, page: Page, opt: PageFileOption) =\u003e MaybePromise\u003cPage | null\u003e;\n}\n```\n\n## 📄 动态配置文件\n\n项目根目录或源码目录下创建 `pages.json.(ts|mts|cts|js|cjs|mjs)` 文件：\n\n```ts\nimport { defineConfig } from '@uni-ku/pages-json';\n\nexport default defineConfig({\n  globalStyle: {\n    navigationBarTextStyle: 'black',\n    navigationBarTitleText: 'uni-app',\n    navigationBarBackgroundColor: '#F8F8F8',\n    backgroundColor: '#F8F8F8',\n  },\n  pages: [\n    {\n      path: 'pages/index/index',\n      style: {\n        navigationBarTitleText: '首页',\n      },\n    },\n  ],\n});\n```\n## 🎯 Vue SFC 中的 definePage 宏\n\n### JS 对象\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\ndefinePage({\n  style: {\n    navigationBarTitleText: '页面标题',\n  },\n  middlewares: ['auth'],\n});\n\u003c/script\u003e\n```\n\n### 函数式\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\ndefinePage(() =\u003e {\n  const title = '动态标题';\n\n  return {\n    style: {\n      navigationBarTitleText: title,\n    },\n    middlewares: ['auth'],\n  };\n});\n\u003c/script\u003e\n```\n\n### 异步函数\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\ndefinePage(async () =\u003e {\n  const title = await fetchTitle();\n\n  return {\n    style: {\n      navigationBarTitleText: title,\n    },\n  };\n});\n\u003c/script\u003e\n```\n\n### 外部模块导入\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport { parse as parseYAML } from 'yaml';\n\ndefinePage(() =\u003e {\n  const config = `\nstyle:\n  navigationBarTitleText: \"YAML 配置\"\nmiddlewares:\n  - auth\n  - logger\n`;\n\n  return parseYAML(config);\n});\n\u003c/script\u003e\n```\n\n### 条件编译\n\n#### 方式一：动态环境变量判断\n\n直接根据环境变量返回不同的对象。\n\n可在配置里手动指定全部平台，避免因为运行时 `platform` 不同导致 `pages.json` 变动。\n\n\u003e **注意：使用第三方库判断环境可能会判断错误。因为部分第三方库初始化时，变量值已经固定，后期环境变量修改无法跟着变更**\n```vue\n\u003cscript setup lang=\"ts\"\u003e\ndefinePage(({ platform }) =\u003e {\n  // 使用注入的 platform 变量\n  const title = platform === 'h5' ? 'H5 环境' : '非 H5 环境';\n  // 使用 process.env.UNI_PLATFORM\n  const bgColor = process.env.UNI_PLATFORM === 'h5' ? 'white' : 'black';\n\n  if (platform === 'mp-weixin') {\n    return null; // mp-weixin 环境下不生成该页面 json\n  }\n\n  return {\n    style: {\n      navigationBarTitleText: title,\n      backgroundColor: bgColor,\n    },\n  };\n});\n\u003c/script\u003e\n```\n\n#### 方式二：条件编译函数\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\ndefinePage(({ define }) =\u003e {\n  return define({\n    style: {\n      navigationBarTitleText: '基础配置',\n    },\n  })\n    .ifdef('mp-weixin', {\n      style: {\n        navigationBarBackgroundColor: '#07C160',\n      },\n    })\n    .ifndef('h5', {\n      style: {\n        enablePullDownRefresh: true,\n      },\n    });\n});\n\u003c/script\u003e\n```\n\n## 🔧 高级功能\n\n### 获取当前平台配置\n\n- 直接通过 `import` 引入 `pages.json` （uniapp 会处理成当前平台的 json 内容）\n- 可通过虚拟模块引入：\n```ts\nimport pagesJson from 'virtual:pages-json';\nconsole.log(pagesJson);\n```\n\n### 类型导入\n\n```ts\nimport type { Page, PagesJson, SubPackage } from '@uni-ku/pages-json/types';\n```\n\n### 与 vite-plugin-uni-platform 集成\n\n```ts\nimport { hookUniPlatform } from '@uni-ku/pages-json/hooks';\n\nexport default defineConfig({\n  plugins: [\n    pagesJson({\n      hooks: [hookUniPlatform],\n    }),\n  ],\n});\n```\n\n## ⚠️ 注意事项\n\n1. **作用域限制**：`definePage` 宏与 SFC 不同域，无法访问 SFC 内部变量\n2. **路径自动生成**：页面路径会根据文件路径自动生成\n3. **单一使用**：每个页面只能使用一次 `definePage`\n4. **平台判断**：避免使用可能被缓存的第三方库进行平台判断\n\n## 📚 示例项目\n\n查看 [playground 示例](./playground/src/pages/define-page/) 了解更多使用方式。\n\n## 🤝 贡献\n\n欢迎提交 Issue 和 Pull Request！\n\n## 📄 许可证\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-ku%2Fpages-json","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Funi-ku%2Fpages-json","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Funi-ku%2Fpages-json/lists"}