PixUI 项目基础配置

PixUI 项目的 webpack 配置。

1. 作者

novlan1

2. 如何使用

安装

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 给其他工具用
  },
});

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

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。

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

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

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

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

5. 更新日志

点此查看