JSON 配置

小程序项目里有大量 app.json / page.json / component.json。weapp-vite 在兼容原生的基础上，额外做了两件更“工程化”的事：

支持 jsonc：允许写注释，读起来更清楚
支持 JSON 别名：让 usingComponents 等路径不用写一堆 ../../

这页聚焦 weapp.jsonAlias：专门用来给 JSON/JSONC 做别名映射。

`weapp.jsonAlias`

类型：{ entries?: Record<string, string> | { find: string | RegExp; replacement: string }[] }
默认值：undefined
适用场景：在大量页面/组件 JSON 中引用同一套公共组件、图标目录或插件路径，希望使用别名提高可读性。

import path from 'node:path'
import { defineConfig } from 'weapp-vite/config'

export default defineConfig({
  weapp: {
    jsonAlias: {
      entries: [
        { find: '@/components/', replacement: path.resolve(__dirname, 'src/components/') },
        { find: /^@icons\//, replacement: path.resolve(__dirname, 'src/assets/icons/') },
      ],
    },
  },
})

配置完成后，可在 JSON/JSONC 中直接使用别名：

jsonc

{
  "usingComponents": {
    "nav-bar": "@/components/navigation-bar",
    "logo-icon": "@icons/logo"
  }
}

构建产物会自动转换为相对路径，确保小程序正确识别：

json

{
  "usingComponents": {
    "nav-bar": "../../components/navigation-bar",
    "logo-icon": "../../assets/icons/logo"
  }
}

TIP

别名匹配规则与 Vite 一致，支持字符串与正则。replacement 建议始终填写绝对路径，以避免因工作目录变化导致解析失败。

与 JS/TS 别名协同

JSON 别名只影响 .json/.jsonc 文件；脚本里的别名仍然由 tsconfig 与 Vite 负责。通常建议同时在 tsconfig.json 里也配一套（让脚本侧也能用 @/）：

json

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

JS/TS 的解析行为可以通过 weapp.tsconfigPaths 微调，两者互不干扰。更多实践示例可参考路径别名指南。

常见问题

别名没有生效？ 请确认 replacement 是否为绝对路径，并检查是否与其他插件产生冲突。
可以给 WXML/WXS 写别名吗？ 这里讲的是 JSON 别名。脚本与模板请继续使用 tsconfig / Vite 的别名方案。
正则别名怎么写？ 可参考上方示例使用 ^@icons\/ 形式；需要捕获变量时也可以使用 RegExp 分组。

下一步：若你还需要调优 JS/TS 的路径解析，请前往 JS 配置了解 weapp.tsconfigPaths 的详细选项。

JSON 配置 ​

weapp.jsonAlias ​

与 JS/TS 别名协同 ​

常见问题 ​

JSON 配置

`weapp.jsonAlias`

与 JS/TS 别名协同

常见问题