一介布衣

🧭 快速导航

WePY 框架快速上手 ​

仓库：https://github.com/Tencent/wepy
文档：https://tencent.github.io/wepy/document.html（部分内容历史版本）
关联清单：https://github.com/justjavac/awesome-wechat-weapp

WePY 是较早期的小程序组件化开发框架，提供类似 Vue 的开发体验（.wpy 单文件组件、数据绑定、事件机制）。随着官方组件化增强和新一代跨端框架兴起，WePY 主要存在于存量项目中。

🎯 目标 ​

  • 使用 WePY 初始化项目并运行
  • 了解 .wpy 组件、数据绑定与事件
  • 掌握存量项目的维护要点与迁移思路

⚙️ 初始化与运行 ​

安装 CLI（若网络不佳建议使用国内源）：

bash
npm i -g @wepy/cli
wepy init standard my-wepy-app
cd my-wepy-app
npm i
npm run dev

用微信开发者工具打开 dist 目录进行预览与调试。

常用脚本：

bash
npm run dev         # 开发
npm run build       # 生产构建

📁 目录结构（示例） ​

my-wepy-app/
├─ src/
│  ├─ app.wpy               # 应用入口
│  ├─ pages/
│  │  └─ index.wpy
│  └─ components/
│     └─ counter.wpy
├─ static/
└─ dist/                    # 编译输出（开发者工具打开此目录）

🧩 .wpy 组件、数据与事件 ​

  • 数据绑定：\{\{ \}\}
  • 事件：@tap="methodName"
  • 组件：usingComponents/components 注册

页面示例（pages/index.wpy）：

html
<template>
  <view class="page">
    <text>计数：\{\{ count \}\}</text>
    <button @tap="inc">+1</button>
    <counter :value.sync="count"/>
  </view>
</template>

<script>
import wepy from '@wepy/core'
import Counter from '../components/counter'

export default class Index extends wepy.page {
  components = { counter: Counter }
  data = { count: 0 }

  inc () { this.count++ }
}
</script>

<style lang="scss">
.page { padding: 24rpx; }
</style>

组件示例（components/counter.wpy）：

html
<template>
  <view class="counter">
    <text>\{\{ value \}\}</text>
    <button @tap="emitInc">+1</button>
  </view>
</template>

<script>
import wepy from '@wepy/core'
export default class Counter extends wepy.component {
  props = { value: { type: Number, default: 0, twoWay: true } }

  emitInc () {
    this.value++
    this.$apply() // 手动触发更新（根据版本差异）
  }
}
</script>

<style>.counter { margin-top: 16rpx; }</style>

提示：不同 WePY 版本在数据更新与事件绑定上细节不同，具体以项目锁定版本与官方文档为准。

🌐 第三方组件与 npm ​

  • 一些 WePY 项目通过 wepy-plugin-npm 支持 npm 依赖，请检查 wepy.config.js 插件配置
  • 与原生自定义组件混用时，注意 usingComponents 的路径与编译产物目录

🏗️ 工程实践（存量项目） ​

  • 锁定 Node 与依赖版本，避免老旧插件引发编译失败
  • 渐进式重构：优先抽离业务逻辑（请求/状态/校验），降低与 WePY 的耦合
  • 真机回归：老项目常有 iOS/Android 差异，功能回归要覆盖主流程
  • 单元与端到端用例：对关键页面与组件补齐基础测试，降低回归风险

🔁 迁移建议 ​

  • 迁往 Taro/uni-app：优先迁移“无 UI 差异的逻辑层”，再迁移视图与交互
  • 迁移路径：
    1. 抽离服务层（请求、存储、埋点）
    2. 在新框架重建路由与页面骨架
    3. 渐进替换组件与样式
  • 风险控制：设立灰度/双线验证，持续对比核心指标（崩溃率、错误率、性能）

🧪 常见问题 ​

  • 编译失败：清理缓存、降级 Node、锁定插件版本
  • 数据不同步：注意 $apply() 或对应版本的数据刷新方式
  • 组件通信异常：核对 props 与事件命名、父子注册关系

✅ 适用场景 ​

  • 维护存量 WePY 项目
  • 渐进式迁移前的过渡维持

🔗 参考 ​

📊 总结 ​

WePY 提供早期的小程序组件化体验。对于存量项目，应以“稳定维护 + 渐进迁移”为策略，抽离通用逻辑，逐步向主流生态迁移以降低长期维护成本。