鸿蒙元服务ASCF配置：打包忽略、启动参数与编译优化

鸿蒙专家

在鸿蒙元服务开发中，除了常见的 app.json 和页面级 .json 配置，还有两个项目级别的配置文件——ascf.config.json 和 ascf.private.config.json。它们位于项目根目录，控制编译行为、打包策略与调试启动参数。合理配置这两个文件，能明显提升日常开发和构建效率。

两个配置文件的分工

ascf.config.json 是公共配置文件，通常提交到代码仓库，团队成员共享。ascf.private.config.json 是个人配置文件，一般不会提交，只影响本地开发环境。两者的参数优先级为：命令行参数 > 个人配置文件 > 公共配置文件 > 系统默认。使用这些配置需要 ASCF Toolkit 版本不低于 1.0.4，部分高级配置项有更高的版本要求。

packOptions：精确控制打包内容

packOptions 是最常用的配置项，用于忽略不需要打包的文件。支持按文件、文件夹、后缀、前缀、glob 模式和正则表达式进行排除，例如：

2. {
3.   "packOptions": {
4.     "ignore": [
5.       { "type": "file", "value": "test/test.js" },
6.       { "type": "folder", "value": "test" },
7.       { "type": "suffix", "value": ".png" },
8.       { "type": "prefix", "value": "sub-" },
9.       { "type": "glob", "value": "test/*.js" },
10.       { "type": "regexp", "value": "^sub.*\\.js$" }
11.     ]
12.   }
13. }

复制代码

需要特别留意：app.json 中配置的页面路径以及实际使用到的组件，不会被 packOptions.ignore 排除。即使写入了匹配规则，这些文件依然会参与打包。如果想用 ignore 剔除测试页面，这条路是走不通的。

launchOptions：调试直达指定页面

launchOptions 仅在 ascf.private.config.json 中生效，用于设置调试时默认启动的页面和参数。例如：

2. {
3.   "launchOptions": {
4.     "path": "page/API/pages/battery/battery",
5.     "query": {
6.       "source": "debug"
7.     }
8.   }
9. }

复制代码

配置后，每次调试都会直接打开电池信息页面，无需手动导航。query 参数可在 App.onLaunch 的 options 中获取：

2. App({
3.   onLaunch(options) {
4.     console.info('启动参数:', JSON.stringify(options));
5.   }
6. });

复制代码

这个功能在调试特定业务页面时非常实用，但要注意它属于 private 配置，其他开发同学拉取代码后不会生效，需要各自在本地创建该文件。

编译性能优化配置

随着项目体积增大，编译耗时越来越明显。以下是原文提到的几项关键优化配置。

使用 swc 替代 babel：默认编译使用 babel，开启 swc 后编译速度明显提升，项目越大效果越明显。

2. {
3.   "swc": true
4. }

复制代码

关闭分包（debug 模式）：仅在调试编译时生效，生产构建不受影响。开发时把分包合并到主包，可以加快构建。

2. {
3.   "disableSubpackages": true
4. }

复制代码

跳过 API 校验：正常编译时会校验 API 和组件的兼容性，跳过可以省下几秒。

2. {
3.   "skipApiValidator": true
4. }

复制代码

缓存开关：默认开启缓存，第一次编译后二次编译会快很多。如果遇到缓存导致的异常，可以关闭。

2. {
3.   "cache": false
4. }

复制代码

templateHoist 减少包体积：当项目使用类 Taro 框架的 base.hxml 模板时，开启该选项可减少重复代码，从而减小包体积，建议开启。

2. {
3.   "templateHoist": true
4. }

复制代码

与编译行为相关的还有日志级别和 source map 配置。日志级别默认为 info，可选 debug < info < warn < error，调试时可设为 debug 获取更多信息。source map 默认是 eval-cheap-source-map，若需要更完整的映射可换成 source-map，但速度会更慢；追求速度可用 eval。

调试相关配置

ascfDebugger 用于开启首行断点，方便从代码第一行开始调试，适用于启动流程排查。

2. {
3.   "ascfDebugger": "brk"
4. }

复制代码

enableDevtools 则用于开启 ASCF Console 调试工具，建议仅在 debug 环境中打开。

2. {
3.   "enableDevtools": true
4. }

复制代码

这两个功能容易被混淆：ascfDebugger 是断点控制，enableDevtools 是调试控制台工具，作用不同。

实验性功能：templateHoist 开启后，base.hxml 构建缓存默认开启，对应配置如下。若遇到异常，可将其关闭。

2. {
3.   "experimental": {
4.     "cacheBaseHxml": true
5.   }
6. }

复制代码

实际项目配置参考

大多数项目使用以下配置即可满足需求。公共配置 ascf.config.json 示例：

2. {
3.   "packOptions": {
4.     "ignore": [
5.       { "type": "folder", "value": "__tests__" },
6.       { "type": "suffix", "value": ".md" },
7.       { "type": "glob", "value": "docs/**" }
8.     ]
9.   },
10.   "swc": true,
11.   "templateHoist": true,
12.   "logging": "info"
13. }

复制代码

个人配置 ascf.private.config.json 示例（不提交）：

2. {
3.   "disableSubpackages": true,
4.   "skipApiValidator": true,
5.   "launchOptions": {
6.     "path": "page/API/pages/appjson/appjson"
7.   },
8.   "enableDevtools": true
9. }

复制代码

常见问题与踩坑记录

packOptions.ignore 对页面路径不生效，这是文档中容易忽略的细节。即使 ignore 中写了匹配规则，app.json 已声明的页面和组件仍会打包。

private 配置只影响本地，ascf.private.config.json 需要开发者自己创建。如果发现 launchOptions 等配置不生效，先检查该文件是否存在且是否被提交。

参数优先级容易混淆，命令行参数最高，其次是 private 配置，然后是 public 配置。例如在 ascf.config.json 中设置 swc: true，但命令行传了 --swc=false，最终会使用 babel。

注意 Toolkit 版本要求，compileMode 需要 >= 1.0.16，enableDevtools 需要 >= 1.0.17 等。版本不足时，配置不会生效。

总的来说，项目级 json 配置虽然平时接触不多，但用好之后对开发效率的提升很明显。swc 编译、缓存、跳过校验这些优化，在项目变大后收益尤其突出。launchOptions 也是一个容易被忽略的好功能，配合 private 配置能省去每次手动跳转页面的操作。