Vue3

.vue3 常用的响应式 API

• ref可以定义任何数据类型的变量，在 JS 中需要通过 .value 获取值；在模板中会自动解包，
• reactive只能定义对象类型的数据，解构后会丢失响应式。
• watch侦听器，用法示例：

watch => {
reset;按理说，getNewsList;})，老实说，

痛点：如果页面没有传入这三个参数。控制台会报错，

改为 getter 的形式可以避免警告。但也会导致 watch 不触发：

watch => startDate,=> endDate,=> categoryList],=> {
reset;按理说，getNewsList;})，

响应式工具函数

• isRef检查某个值是否为 ref
• unref如果参数是 ref返回内部值，否则返回参数本身。
• toRef将普通值、ref 或 getter 转换为 ref
• toValue类似 unref,同时规范化 getter 函数。
• toRefs把响应式对象转换为普通对象。每个属性都就是向源对象属性的 ref

.keep-alive 缓存失效的原因与方法

Pain Point： 的 include/exclude 属性是基于组件的 Name 匹配，而不是路由的 name。重复使用同名组件（如多个 /src/views/index.vue) 时匹配失败。

解决办法：

1. a) 在组件中手动设置唯一的 Name
2. b) 使用插件  让 script setup 能直接声明 name。

.列表页缓存策略

说到方式一，利用路由 meta 标记是否从详情页返回

{
path这方面，'/newsList/:newsType',name: 'newsList',component: => import,meta: {
requiresAuth: true。needCache: true,isBackFromDetail: false,},}

defineOptions({
从name来看，'newsList',beforeRouteEnter {
to.meta.isBackFromDetail = from.name === 'newsDetail';},})，按理说，

Pain Point：SFC 中的 setup 无法直接使用路由守卫。需要放在 script 块或使用 defineOptions 包装。

onActivated => {
// 非“从详情返回”时重新请求数据
if {
reset;getNewsList，}
// 重置标记，防止下次误判
route.meta.isBackFromDetail = false;})，老实说，

*缺点*：当页面状态复杂时需要手动清空大量数据。易产生 bug，

方式二的观点是，基于 keep-alive + Pinia 动态维护缓存列表

Pain Point：No‑Cache‑When‑From‑Home but Keep Cache on Browser Back/Forward.

// src/stores/cached-view.ts
import { defineStore } from 'pinia';不过，export const useCachedViewStore = defineStore => {
const cachedViewList = ref;

function addCachedView { if ) { cachedViewList.value.push;} }

function delCachedView { const idx = cachedViewList.value.indexOf;if cachedViewList.value.splice;return idx> -1;}

async function delCacheEntry { if ) { await nextTick;addCachedView;} }

return { cachedViewList。addCachedView,delCachedView,delCacheEntry };})，

router.beforeEach => { const { addCachedView } = useCachedViewStore;addCachedView;})，

defineOptions({ 从name来看，'newsList'。beforeRouteEnter { if { const { delCacheEntry } = useCachedViewStore;delCacheEntry;} },})，

Pain Point：If you delete cache in a global navigation guard it also removes history‑back caches. The workaround is to clear cache only on explicit navigation from Home:

// 首页点击入口前手动清除
const { delCacheEntry } = useCachedViewStore;const handleGridClick = newsType => {
delCacheEntry;router.push，};

vue-router 深入解析 & 痛点汇总

.不同的历史记录模式 & 子目录部署

• Pain Point：The project uses History mode. When deploying under a sub‑directory you must set `base` in vite config and adjust server fallback.
• `vite.config.js` 示例：

export default defineConfig({
base的观点是。'/my-sub-path/',plugins:,});

.params vs query 参数选择

Pain Point：`params` 参数顺序敏感且可选参数多时容易出现错位；切换页面后浏览器前进/后退导致获取不到正确值。说起来，

# 推荐使用 `query` 参数：

• - URL 可读性强。一眼看出传递了哪些属性，
• - 所有值都会被字符串化，需在业务层做类型转换。
• - 示例：

// 路由定义
{
path的观点是，'/newsList'。name: 'newsList',component: => import
}

// 页面获取 const route = useRoute;其实，const newsType = Number;// 手动转型

.公司微信回调地址获取 `code` 的坑

Pain Point：`redirect` 本身带有 query 时拼接后的 `?` 会导致两层 query 难以解析；而不带 query 时`?` 紧跟在方法后一样需要特殊处理。

• A. 带 query 的场景 URL 示例： /login?不过，redirect=/newsList?newsType=1&code=xxxxxx 此时应通过解析 `redirect` 再从其中取 ` code `。不过，
• B. 不带 query 的场景 URL 示例： /login?redirect=/home?&code=xxxxxx 直接读取 `location.search` 即可获得 ` code `。说起来，

Vite 实际方法 & 常用插件

.项目中常用的 Vite 插件

• .vite-plugin-vue-setup-extend: 让 script setup 可以直接声明组件 ``。bash npm i vite-plugin-vue-setup-extend -D js // vite.config.js import vueSetupExtend from 'vite-plugin-vue-setup-extend';export default defineConfig({ plugins:,});
• .unplugin-auto-import: 自动导入 Vue、Router、Pinia 等 API。其实，bash npm i unplugin-auto-import -D js import AutoImport from 'unplugin-auto-import/vite';export default defineConfig({ plugins: sx?$/,/\.vue$/,/\.vue\?vue/,/\.md$/],imports:,}),],});
• .unplugin-vue-components + VantResolver: 组件库按需自动引入。bash npm i unplugin-vue-components -D @vant/auto-import-resolver js import Components from 'unplugin-vue-components/vite';import { VantResolver } from '@vant/auto-import-resolver';export default defineConfig({ plugins: })。],})，
• .vite-plugin-svg-icons: 生成 SVG 雪碧图，统一管理图标。bash npm i vite-plugin-svg-icons -D js import { createSvgIconsPlugin } from 'vite-plugin-svg-icons';export default defineConfig({ plugins:,symbolId:'icon-'。inject:'body-last',customDomId:'__svg__icons__dom__',}) ] });

.环境变量配置与使用

"环境变量" 与 "模式" 是两个概念。不同模式可以对应不同的 .env 文件，如 .env.development、.env.test、.env.production。通过 读取对应值。

json // package.json scripts 示例 { "scripts": { 从"dev"来看，"vite","dev:test": "vite --mode test","build": "vite build","build:test": "vite build --mode test"。"preview": "vite preview" } }

.静态资源引用技巧

• - 使用绝对公共方法或相对方法均可，但在生产建立时优先使用 ES 模块化的 URL 引入方式： js import logoUrl from '@/assets/logo.png';// Vite 自动处理文件哈希与 basePath。再看or，js const iconUrl = new URL.href;
• - 案例一：Vant 的 `` 若直接写相对方法可能显示不出来需要使用上面的 URL 方法包装后传入 src 属性。
• - 案例二：生产环境部署后出现静态资源找不到错误，是因为代码中用了类似 `` 的写法。Vite 不会解析该相对方法，必须改成上述 URL 写法或使用 `import …` 来确保资源被打包并生成正确哈希方法。
• - 当资源体积非常小，Vite 会默认转成 base64 内联。如果想关闭，可在 vite.config.js 中配置： js export default defineConfig({ assetsInlineLimit:0 // 禁用内联。把所有文件都单独输出，});**Pain Point**：不想让图片被 base64 打包导致缓存失效时可自行调节阈值。

  Pinia 状态管理实战 & 常见陷阱

  .store 响应式细节

  "store" 本质上是一个经过 reactive 包装的对象。若在 setup 中直接解构，会失去响应式：

  // ❌ 错误写法。会导致页面不更新
  import { useNewsStore } from '@/stores/news';const { newsType,getNewTypes } = useNewsStore;getNewTypes，// UI 不会响应变化
  
  The correct way is to keep store object intact or use **storeToRefs**:
  // ✅ 正确写法
  import { storeToRefs } from 'pinia';const newsStore = useNewsStore;const { newsType } = storeToRefs;// 响应式 ref
  const { getNewTypes } = newsStore;// action 可直接解构
  // 或者直接使用 computed 包装属性
  const newsType = computed => newsStore.newsType);Pain Point： 当你把整个 store 解构后再调用 action。action 本身仍然可用，但关联状态已经失去响应式，导致 UI 不更新。
  
  Shrink or Share State?
  
  从*思考*来看，哪些状态应该放进 Pinia？如果仅在少数页面间共享且逻辑简单，可以抽象成自定义 Hook；但若涉及跨页面、持久化或需要统一管理，则推荐放进 Pinia。以免出现“多处副本”导致状态不一致的问题。
  
  Bizarre Bug – List API 被意外触发 🚩​​​​​​​​​​​​​​​​​​​​​​​​​​​​ ​​​​​​​​​​​​​ ​‌‍‍‍‍‍‍‍‍‌ ‌‌‌‏‏‏‏‏‏‏‎‎‎‎‎‌ ‎ ‎ ‎ ‎ ‎ ‎ ‌ ‍ ‍ ‍ ‍ ‍ ‌‌‌‌      ​‌️️️️️️️️️️
  
  A list page navigates to detail page. The hook that watches input parameters for list still fires after navigation because its effect scope wasn't disposed.
  Pain Point : watch 副作用没有在离开页面时销毁。可以尝试把 watch 包裹在 **effectScope** 中，在 onUnmounted 时手动 stop。老实说，js
  import { effectScope } from '@vue/reactivity';onMounted => {
  const scope = effectScope;scope.run => {
  watch;})，onUnmounted => scope.stop);})，
  
  Vant4 实际坑点与常用方法 
  
  
  Field 输入框数值类型问题 ：type 为 number 时 v-model 返回 string。即使加了 number 修饰符，formatter 接收仍是 string。只有提交阶段才会转换成 number。其实，校验 validator 一样接收 string。需要自行转型或在 rules 中处理。
  
  
  Dialog 默认行为冲突 ：confirm 按钮点击后会自动关闭弹窗，即便表单未校验通过。说到解决办法，
  
  
  使用 before-close 阻止默认关闭；或者自定义底部按钮，通过 click 手动调用 close。不过，
  
  宽度默认320px。如果全局懒加载路由导致样式覆盖异常，请改为路由懒加载方式加载首页组件，以确保 CSS 正确注入。
  ...
  ...
  ...
  ...
  
  
  
  公司微信内部应用
  
  如何接入公司微信 SDK
  Pain Point : SDK 必须在每个需要调用它的页面先进行注册，否则读取到的 URL 与实际不符。**方法**这方面，1️⃣ 在对应页面生命周期最早阶段调用：
  js
  import wx from '@jssdk/wechat';// 假设已安装官方 SDK
  onMounted => {
  wx.config;})，
  
  附件下载与预览
  
  
  
  场景
  实现方式
  注意事项
  
  
  
  
  移动端预览
  调用 wx.previewFile
  必须先注册 SDK；网络异常需提示使用者 “下载失败，请检查网络”。其实，
  
  
  PC端下载
  使用 下载附件 或 window.open
  跨域资源需服务器设置 CORS。否则无法打开，老实说，
  
  
  
  Pain Point :iOS/Android Webview 下 `window.open` 与跨域链接无法打开。只能走 SDK 或后台代理下载。
  
  
  TODO 列表
  
  
  VueUse 换肤 – 利用 prefers-color-scheme 媒体特性实现暗黑模式切换，并持久化使用者选择到 localStorage；
  
  主题 CSS Variable – 定义 { --bg:#000;--text:#fff，} 并通过  动态切换；
  
  全局暗色类 – document.documentElement.classList.toggle;.
  
  
  
  
  
  
  
  

---