PixUI 项目基础配置

PixUI 项目的 webpack 配置。

1. 作者

novlan1

2. 如何使用

安装

bash

pnpm add @plugin-light/project-config-pixui -D

在 .pixiderc/webpack.js 中添加如下设置：

const { getPixuiWebpackConfig } = require('@plugin-light/project-config-pixui');

module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
});

3. 类型及默认参数

3.1. 参数

getPixuiWebpackConfig 接收一个对象作为参数。

属性	类型	说明	默认值
appSettingDir	`string`	`apps.json` 和 `appsettings.json` 文件所在目录	-
tsxLoaderExclude	`regexp`	`tsx` 相关 `loader` 排除路径	`/node_modules\/(?!@tencent\/pmd\|@tencent\/press)/`
port	`number`	启动端口号	`8080`
useTailwind	`boolean`	是否使用 tailwindcss	`false`
ifdefOptions	`boolean \| Record<string, any> \| ((v: Record<string, any>) => Record<string, any>)`	是否使用 ifdef-loader	`true`
crossGameStyleOptions	`boolean \| Record<string, any>`	是否使用 cross-game-style-loader	-
usePMDNetworkV2	`boolean`	是否使用 `pmd-network-v2` 替代 `pmd-network`	`false`
optimization	`Record<string, any>`	自定义 webpack `optimization` 配置，会与默认值 `{ minimize: false }` 浅合并	`{ minimize: false }`
tsCheckerOptions	`boolean \| Record<string, any> \| ((isShipping: boolean) => Record<string, any>)`	TypeScript 类型检查（`ForkTsCheckerWebpackPlugin`）开关与配置，详见 3.5	`true`

3.2. 类名

less 文件中的类名采用 modules 方式。

{
  loader: require.resolve('css-loader'),
  options: {
    modules: {
      localIdentName: '[name]_[local]__[hash:base64:6]',
    },
  },
}

3.3. 构建产物体积上报

通过 reportBundleSize 配置可以在生产构建结束后自动统计产物体积、计算 zip 体积、收集 git 信息并上报。

module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  // 直接开启，使用默认上报地址
  reportBundleSize: true,
});

// 也可传对象自定义
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  reportBundleSize: {
    // 可选：覆盖默认上报地址
    // reportUrl: 'https://mobile.aow.com/tapd-solution-cgi/open/bundle-size-report',
    // 可选：覆盖默认启用条件
    // enabled: true,
    // 可选：附带额外上报字段
    // extra: { bizTag: 'pubgm-official' },
  },
});

字段	类型	说明	默认值
`reportUrl`	`string`	上报接口完整 URL	`https://mobile.aow.com/tapd-solution-cgi/open/bundle-size-report`
`enabled`	`boolean \| (c) => boolean`	是否启用	仅生产构建启用
`skipSourceMap`	`boolean`	是否跳过 `.map` 文件	`true`
`projectRoot`	`string`	git 信息目录	`compiler.context`
`extra`	`Record<string, any>`	上报体额外字段	-
`timeout`	`number`	上报超时（ms）	`10000`
`verbose`	`boolean`	是否打印日志	`true`

也支持单独导入 ReportBundleSizePlugin 自行挂载到任意 webpack 配置：

 const { ReportBundleSizePlugin } = require('@plugin-light/project-config-pixui');

3.4. 包体积可视化分析

通过 bundleAnalyzer 接入 webpack-bundle-analyzer，构建后会在产物目录下生成 bundle-report.html，浏览器打开即可看到可缩放的 treemap。

// 简单开启
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  bundleAnalyzer: true,
});

// 自定义参数
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  bundleAnalyzer: {
    analyzerMode: 'server',     // 启动本地 HTTP 服务自动打开浏览器
    analyzerPort: 8888,
    openAnalyzer: true,
    generateStatsFile: true,    // 同时输出 stats.json 给其他工具用
  },
});

也支持临时通过环境变量打开（用默认参数）：

bash

BUNDLE_ANALYZE=1 pnpm build

默认参数：{ analyzerMode: 'static', reportFilename: '../bundle-report.html', openAnalyzer: false, defaultSizes: 'parsed' } 启用前请确保业务工程已安装：pnpm add -D webpack-bundle-analyzer

3.5. TypeScript 类型检查

通过 tsCheckerOptions 控制 fork-ts-checker-webpack-plugin 的开关与配置，支持四种入参形态：

入参	行为
不传 / `true`	默认行为：`isShipping === true` 时使用 `{ async: false }`（类型错误阻断构建）；`isShipping === false` 时使用 `{ async: true, typescript: { memoryLimit: 8192 } }`（dev 异步检查 + 提高子进程内存上限，避免大型工程 HMR 时 OOM）
`false`	完全关闭 ts 类型检查，不挂载 `ForkTsCheckerWebpackPlugin`
`(isShipping) => config`	函数：以 `isShipping` 为入参，返回值作为 `ForkTsCheckerWebpackPlugin` 的配置
`Record<string, any>`	对象：直接作为 `ForkTsCheckerWebpackPlugin` 的配置

// 关闭 ts 类型检查（不会挂载插件）
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  tsCheckerOptions: false,
});

// 直接给一份固定配置
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  tsCheckerOptions: {
    async: true,
    typescript: { memoryLimit: 4096 },
  },
});

// 根据 isShipping 动态返回配置
module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  tsCheckerOptions: (isShipping) => ({
    async: !isShipping,
    typescript: {
      memoryLimit: isShipping ? 4096 : 8192,
    },
  }),
});

4. FAQ

4.0. 关于 optimization

默认配置为 { minimize: false }。如需自定义（例如开启压缩、配置 splitChunks 等），可通过 optimization 参数传入，会与默认值进行浅合并，传入的字段会覆盖同名默认字段：

module.exports = getPixuiWebpackConfig({
  appSettingDir: __dirname,
  optimization: {
    minimize: true,
    splitChunks: {
      chunks: 'all',
    },
    runtimeChunk: 'single',
  },
});

注意：是浅合并，optimization 内部的对象（如 splitChunks）会被整体覆盖，而不是深合并。

4.1. 关于 tailwindcss

PixUI 不支持 CSS 变量，tailwindcss 使用严重受限，不建议在 PixUI 中使用 tailwindcss。

4.2. 关于条件编译

默认开启条件编译，可以通过 ifdefOptions 参数关闭。

module.exports = getPixuiWebpackConfig({
  ifdefOptions: false,
})

开启时，默认参数如下：

{
  context: {
      PIXUI: true,
      REACT: true,
      __NOT_UNI__: true,
    },
  type: ['css', 'js', 'html'],
}

即可以支持下面写法：

// #ifdef PIXUI
console.log('hello novlan1')
// #endif

/* #ifdef PIXUI */
console.log('hello novlan1')
/* #endif */

可以通过 ifdefOptions 参数修改默认参数：

module.exports = getPixuiWebpackConfig({
  // 传入对象
  ifdefOptions: {
    context: {
      XXX: true,
      __NOT_UNI__: true,
    },
    type: ['css', 'js', 'html'],
  },
  // 或传入函数
  // ifdefOptions: (config) => ({
  //   context: {
  //     ...config.context,
  //     XXX: true,
  //   },
  // }),
})

4.3. 样式关键词编译

即 @TIP_STYLE_NAME 关键词替换，基础配置默认支持。

参数完全透传给 cross-game-style-loader
查找路径，目录/css/xx.less
不支持数组形式的 styleName，因为引入形式是 ESM 语法，而不是 @import

使用方式

src/config.js 中声明 styleName，如 pubgm。

module.exports = {
  styleName: 'pubgm',
}

组件文件引入样式带上关键词 @TIP_STYLE_NAME。

tsx

// @ts-ignore
import styles from '@TIP_STYLE_NAME';

const XXComp = () => {
  return <div className={styles.root}>Hello World</div>;
};

组件所在目录放上对应样式文件。

bash

- one-dir
  - XXComp # 组件
  - css
    - pubgm.less

5. 更新日志

点此查看

PixUI 项目基础配置 ​

1. 作者 ​

2. 如何使用 ​

3. 类型及默认参数 ​

3.1. 参数 ​

3.2. 类名 ​

3.3. 构建产物体积上报 ​

3.4. 包体积可视化分析 ​

3.5. TypeScript 类型检查 ​

4. FAQ ​

4.0. 关于 optimization ​

4.1. 关于 tailwindcss ​

4.2. 关于条件编译 ​

4.3. 样式关键词编译 ​

5. 更新日志 ​

PixUI 项目基础配置

1. 作者

2. 如何使用

3. 类型及默认参数

3.1. 参数

3.2. 类名

3.3. 构建产物体积上报

3.4. 包体积可视化分析

3.5. TypeScript 类型检查

4. FAQ

4.0. 关于 optimization

4.1. 关于 tailwindcss

4.2. 关于条件编译

4.3. 样式关键词编译

5. 更新日志