defineOiyoConfig

声明 Oiyo 工程级约定与扫描目录

defineOiyoConfig() 用于声明 Oiyo 的工程级约定，常见场景包括配置“主包/分包”的页面目录，以及调整自动扫描的来源范围。

使用位置

文件名：oiyo.config.{ts,js,mjs}
目录：项目根目录（与 package.json 同级）
导出：默认导出

oiyo.config.ts

import { defineOiyoConfig } from '@skiyee/oiyo/config'

export default defineOiyoConfig({
  // ...
})

看项目结构里的 oiyo.config.ts 说明

签名

defineOiyoConfig(config: OiyoConfig): OiyoConfig

该函数的主要作用是提供稳定的配置结构与类型提示。

字段

OiyoConfig

属性	类型	默认值	说明
`rootDir`	`string`	`process.cwd()`	项目根目录，通常不需要手写。
`srcDir`	`string`	`'src'`	源码目录（相对 `rootDir`）。
`dir`	`OiyoConfigDir`	`OiyoConfigDir`	目录约定配置（主包 pages、subPackages、layouts、中间件目录等）。
`scan`	`OiyoConfigScan`	`OiyoConfigScan`	自动扫描来源配置，用于约定组件与 API 的扫描范围。
`exclude`	`string[]`	`['/components/', '/composables/', '/utils/']`	扫描页面/布局时的排除规则（glob），会与内置默认值合并。（相对 `srcDir`）
`ide`	`OiyoConfigIde`	`OiyoConfigIde`	不同平台 IDE 的功能配置

OiyoConfigDir

属性	类型	默认值	说明
`mainPackage`	`string`	`'pages'`	主包页面根目录（相对 `srcDir`）。
`subPackages`	`string[]`	`[]`	分包页面根目录列表（相对 `srcDir`）。
`layouts`	`string`	`'layouts'`	布局目录（相对 `srcDir`）。
`middleware`	`string`	`'middlewares'`	中间件目录约定（相对 `srcDir`）。

OiyoConfigScan

属性	类型	默认值	说明
`apis`	`ApiScanner`	`ApiScanner`	自动扫描可直接使用的 API 来源。
`components`	`ComponentScanner`	`ComponentScanner`	自动扫描可直接使用的组件来源。

ApiScanner

ApiScanner 支持两种写法：

string：直接声明扫描来源，例如 composables、@scope/pkg
object：按需细化扫描范围、过滤条件和暴露名称

属性	类型	默认值	说明
`from`	`string`	-	扫描来源。可用于目录、文件、包名或包子路径。
`types`	`boolean`	`false`	是否同时处理类型导出。
`pattern`	`string \| string[]`	-	只匹配这些文件。适合进一步收窄扫描范围。
`ignore`	`string \| string[]`	-	忽略这些文件。适合排除测试文件或临时目录。
`only`	`ScanName[]`	-	只保留这些导出，并可按需重命名。
`exclude`	`string[]`	-	排除这些最终暴露名。

ScanName 支持：

string：直接使用原始导出名
{ name, as?, isType? }：声明来源名、重命名和是否按类型处理

ComponentScanner

ComponentScanner 同样支持两种写法：

string：直接声明扫描来源，例如 components
object：按需细化扫描规则、命名规则和暴露范围

属性	类型	默认值	说明
`from`	`string`	-	扫描来源。可用于目录、文件、包名或包子路径。
`pattern`	`string \| string[]`	-	只匹配这些文件。
`ignore`	`string \| string[]`	-	忽略这些文件。
`only`	`ScanName[]`	-	只保留这些组件导出，并可按需重命名。
`prefix`	`string`	-	为最终组件名添加统一前缀。
`chain`	`boolean`	-	是否让目录链参与组件命名。

OiyoConfigIde

属性	类型	默认值	说明
`ide.open`	`boolean`	`false`	构建小程序平台时自动打开对应 IDE。
`ide.path`	`Partial<Record<string, string>>`	`{}`	不同平台 IDE 的可执行路径映射。

属于实验性功能，如若有问题可直接反馈。

基础示例

oiyo.config.ts

import { defineOiyoConfig } from '@skiyee/oiyo/config'

export default defineOiyoConfig({
  dir: {
    mainPackage: 'pages',
    subPackages: ['sub-direct', 'sub-nested/order'],
  },
  scan: {
    apis: ['composables'],
    components: ['components'],
  },
})

约束

dir.subPackages 声明的是“会参与分包页面扫描/注册”的目录，不是随意的文件夹清单
路径建议使用 / 作为分隔符，以保证跨平台一致性
scan 适合用来收敛团队约定，文档中只建议声明业务侧需要感知的扫描来源

自动路由：扫描与生成机制

学习如何通过目录约定将页面拆分到分包中

API 参考

Oiyo 配置、运行时、宏、组件与 CLI 的权威参考

definePagesConfig

声明全局 pages.json 配置（globalStyle/tabBar 等）