更新记录

1.2.0（2026-09-18） 下载此版本

• 新增 setupWcVersionGlobals(app)：全局 mixin 向所有组件混入 versionHidden / versionReleased 计算属性，页面模板零接线直接 v-if="!versionHidden"（须在 createPinia 之后、createApp 内调用一次）。
• 同文件内含 ComponentCustomProperties 类型增强（declare module 'vue'），模板里 versionHidden / versionReleased 有 TS 类型提示。
• 既有 API（versionHidden getter / isVersionHidden() / requireVersionPage()）不变；新旧开关共用同一全局判定，三端语义一致。

1.0.0（2026-09-17） 下载此版本

• 首个版本：封装自 won-passion-for-sports（uni1）的 modules/system（siteConfig 比对）+ shared/auth-gate 的 requireVersionPage。
• commons/store.ts：Pinia store（configs / remoteVersion / localVersion / versionReleased），启动预热、失败保守不放行。
• commons/gate.ts：requireVersionPage() 页面级守卫（未放行 redirectTo 404 页）。
• commons/config.ts：setupWcVersion({ localVersion, notFoundUrl }) 宿主注入本地版本线与 404 页路由（插件不读项目环境变量）。
• 接口对接本项目 server：GET /core/mobile/system/siteConfig（公开，site_config 配置组键值对）。

平台兼容性

uni-app(5.24)

uni-app x(5.24)

wc-version

站点配置 + 版本灰度开关：启动时拉取 siteConfig 与本地版本线比对， 线上 version > 本地 → versionReleased = true（功能放行）；否则整体收回 （受控页面直达 404、入口隐藏）。反向布尔开关 versionHidden / isVersionHidden() （本地（线下）≥ 线上 → true = 需要隐藏）；setupWcVersionGlobals(app) 再混入 全局模板开关（页面零接线 v-if="versionHidden"）。封装自 uni1 的 modules/system + requireVersionPage。

工作机制

• 本地版本线：.env 的 VITE_VERSION（数值），随包发布递增；
• 线上版本线：后台 site_config 配置组的 version key（运营随时可调）；
• 线上 > 本地 → 放行；线上 ≤ 本地 / 配置未加载 / 拉取失败 → 保守不放行；
• 运营调高 version → 新包恢复可用；调低 → 整体收回（全局开关 / 强制升级手段）。

宿主接线（main.ts）

import { setupWcVersion } from '@/uni_modules/wc-version/commons/config'
import { setupWcVersionGlobals } from '@/uni_modules/wc-version/commons/globals'
import { useVersionStore } from '@/uni_modules/wc-version/commons/store'

// 本地版本线（.env 注入；插件不读环境变量，与 wc-auth 的 wcappid 约定一致）
setupWcVersion({
    localVersion: Number(import.meta.env.VITE_VERSION) || 0,
    notFoundUrl: '/pages/not-found/index', // 缺省即此值，404 页需宿主自备
})

// 全局模板开关：所有页面 / 组件模板零接线直接 v-if="versionHidden"
// （须在 createPinia 之后调用，内部捕获 version store）
setupWcVersionGlobals(app)

// 站点配置预热：启动拉一次（公开接口、silent 失败不弹 toast），此后全局读缓存。
// 失败静默保守收回，下次进入受控页面不重试（与 uni1 行为一致）
void useVersionStore().fetchSiteConfig().catch(() => {})

.env（生产）/.env.development（开发，调高便于日常联调不受控）：

VITE_VERSION = 1

使用

模板 v-if（推荐：全局零接线，无需 script）

main.ts 接好 setupWcVersionGlobals(app)（见上文接线）后，所有页面 / 组件模板 直接用 versionHidden（true = 需要隐藏） / versionReleased（反面，true = 已放行）：

<template>
    <!-- 受控入口：versionHidden = true（线下 ≥ 线上）→ 隐藏 -->
    <view v-if="!versionHidden" @tap="goSomething">受控入口</view>
    <!-- 仅隐藏期间展示（占位 / 敬请期待） -->
    <view v-if="versionHidden">敬请期待</view>
    <!-- 与 v-if="!versionHidden" 完全等价 -->
    <view v-if="versionReleased" @tap="goSomething">受控入口（等价写法）</view>
</template>

• 开关响应式：跟随 siteConfig 预热与运营调线自动翻转，无需 watch；
• 冷启动未加载时保守为 true（隐藏），预热回来后自动恢复，与页面守卫口径一致；
• 仅模板可直接用；<script setup> 的 JS 代码里 mixin 计算属性不进 script 作用域， 命令式判断仍用 isVersionHidden()；
• 页面自身若有同名 versionHidden / versionReleased computed / data， 自身定义优先（Vue mixin 合并规则：组件覆盖全局）。

模板 v-if（未接全局混入时的 store 形式）

<script setup lang="ts">
import { useVersionStore } from '@/uni_modules/wc-version/commons'
const versionStore = useVersionStore()
</script>

<template>
    <view v-if="!versionStore.versionHidden" @tap="goSomething">受控入口</view>
    <view v-if="versionStore.versionHidden">敬请期待</view>
</template>

命令式调用（onLoad / 提交前 / 拦截器等）

线下（本地）版本线 ≥ 线上 version → isVersionHidden() 返回 true = 需要隐藏 （相等、配置未加载、拉取失败、后台未配置 version 时也保守返回 true）； 已放行（线上 > 本地）返回 false，正常展示。

import { isVersionHidden } from '@/uni_modules/wc-version/commons'

const onSomething = () => {
    if (isVersionHidden()) return // 线下 ≥ 线上 → 未放行，隐藏 / 跳过
    // …已放行的正常逻辑
}

页面级守卫（挡分享 / 直达路径，onLoad 首行）

import { requireVersionPage } from '@/uni_modules/wc-version/commons'

onLoad(() => {
    if (!requireVersionPage()) return // 未放行已跳 404，停止初始化
    void initPage()
})

API

行为约定

范围说明

刻意不包含（保持简单）：

• App / 小程序整包升级检测（uni.getUpdateManager，需要时另封装）
• 按用户 / 百分比的细分灰度（只有全局版本线开关）
• siteConfig 其它 key 的业务语义（configs 原样暴露，宿主自行取用）