VUE3学习 第二章 vite认识 SFC语法规范 VUE3-vscode插件 npm run dev执行过程详解 模板语法和V3指令｜TaoToken 统一 Key 打通本地调试链路

1. 从 vite 目录到 npm run devVUE3 第二章本地调试链路怎么跑通VUE3 第二章的学习路径很多人卡在一个很具体的地方项目能跑起来但说不清npm run dev到底做了什么.vue文件能写但不知道template、script setup、style三块是怎么被编译成浏览器认识的代码插件装了一堆Volar 和 Vetur 打架导致类型提示全红。这一章要解决的就是这条链路vite 认识、SFC 语法规范、VUE3-vscode 插件配置、npm run dev 执行过程、模板语法和 V3 指令最后把本地调试请求的 endpoint 统一改到 TaoToken用一把 Key 完成一次可复现的联调验证。先说清楚这套东西是什么、能做什么、适合谁。vite 是 VUE3 官方推荐的构建工具它的核心特点是开发阶段不打包浏览器请求哪个模块就编译哪个模块所以冷启动快。SFCSingle-File Component是.vue文件的写法规范一个文件里同时写模板、逻辑和样式。VUE3-vscode 插件负责让编辑器认识这些语法给出类型提示和错误检查。npm run dev是把这三者串起来的启动命令。适合刚学完 VUE3 基础语法、准备动手写第一个完整组件、但被工程化细节绊住的人。我试过在同一个项目里同时开着 Vetur 和 Volar结果script setup里的ref一直报「找不到名称」排查了半小时才发现是插件冲突。这一章会把这类坑提前标出来。整章的结构是这样先讲 vite 目录和 SFC 规范再讲插件配置然后拆npm run dev的执行过程接着写模板语法和指令的实战代码最后把请求 endpoint 改到 TaoToken 做联调验证并给出常见报错排查。每一步都有可复制的配置和命令跟着敲就能跑通。2. vite 目录结构与 SFC 语法规范VUE3 单文件组件写法详解2.1 vite 项目目录里每个文件夹到底干什么用npm create vitelatest建出来的 VUE3 项目根目录大概长这样my-vue3-app/ ├── public/ ├── src/ │ ├── assets/ │ ├── components/ │ ├── App.vue │ └── main.ts ├── index.html ├── vite.config.ts ├── package.json └── tsconfig.jsonpublic下面的文件不会被编译原样拷贝到产物目录适合放favicon.ico、robots.txt这类不需要处理的静态资源。src/assets下面放需要被编译的资源比如图片、样式文件vite 会处理它们的引用路径。src/components放组件App.vue是根组件main.ts是全局入口脚本。重点说index.html。webpack、rollup 这类工具的入口是一个 JS 文件entry input而 vite 的入口是一个 HTML 文件。vite 启动时不会立刻编译所有 JS只有浏览器请求到script typemodule src/src/main.ts时vite 拦截这个请求才去解析对应的模块。这就是 vite 开发态快的根本原因按需编译。vite.config.ts是配置文件后面改 endpoint 就在这里动手。2.2 SFC 三种顶层语法块的规范每个.vue文件由三种顶层块组成template、script、style。template每个文件最多一个顶层块。它的内容会被提取出来交给vue/compiler-dom预编译成 JavaScript 渲染函数挂到导出组件的render选项上。script可以有多个不含script setup作为 ES Module 执行默认导出应该是组件选项对象要么是普通对象要么是defineComponent的返回值。script setup每个文件最多一个会被预处理成组件的setup()函数在每个组件实例中执行。这是 VUE3 组合式 API 的推荐写法。style可以有多个通过scoped或module属性把样式封装在当前组件内不同封装模式的style可以在同一个组件里混用。一个完整的 SFC 长这样template div classbox{{ message }}/div /template script setup langts import { ref } from vue const message ref(hello vue3) /script style scoped .box { color: #42b883; } /stylescoped会给样式加上唯一属性选择器避免污染其他组件。如果你需要全局样式去掉scoped即可。2.3 VUE3-vscode 插件配置清单打开 VS Code 扩展面板搜索并安装插件名作用是否必装Vue Language Features (Volar)VUE3 语法高亮、类型提示、模板检查必装TypeScript Vue Plugin (Volar)让 TS 文件认识.vue导入必装ESLint代码规范检查可选Prettier代码格式化可选注意VUE3 的 Volar 和 VUE2 的 Vetur 不能同时开启会冲突。如果你之前装过 Vetur在扩展面板里把它禁用或卸载然后重启 VS Code。判断是否生效的方法打开一个.vue文件script setup里的变量在template中应该有类型提示鼠标悬停能看到类型。如果提示不生效检查 VS Code 右下角语言模式是不是Vue以及settings.json里有没有把.vue关联到错误的语言。可以在settings.json加{ files.associations: { *.vue: vue } }3. npm run dev 执行过程与 vite.config.ts 可复制配置3.1 npm run dev 到底执行了什么执行npm run dev时npm 先去找package.json的scripts字段{ scripts: { dev: vite, build: vue-tsc --noEmit vite build, preview: vite preview } }找到dev对应的vite命令。但电脑上并没有全局安装 vite为什么能执行因为npm install时vite 作为依赖被装进node_modules同时在node_modules/.bin/下创建了可执行文件的软链接。.bin目录不是任何一个 npm 包里面的文件是软链接。打开node_modules/.bin/vite顶部写着#!/bin/sh说明它是个脚本。npm 执行npm run xxx时会通过软链接找到node_modules/vite再看 vite 包里的package.json{ bin: { vite: bin/vite.js } }于是找到bin/vite.js来执行。查找规则是先从当前项目的node_modules/.bin找找不到去全局node_modules/.bin找再找不到去环境变量 PATH 找。node_modules/.bin里通常有三个 vite 文件viteUnix/Linux/macOS 默认可执行文件必须输入完整文件名、vite.cmdWindows cmd 默认不写后缀时按 PATHEXT 查找、vite.ps1Windows PowerShell 可执行。Windows 一般执行第二个macOS/Linux 执行第一个。3.2 vite.config.ts 可复制配置片段下面这份配置可以直接复制到项目根目录的vite.config.ts包含路径别名、开发服务器端口和代理import { defineConfig } from vite import vue from vitejs/plugin-vue import { fileURLToPath, URL } from node:url export default defineConfig({ plugins: [vue()], resolve: { alias: { : fileURLToPath(new URL(./src, import.meta.url)) } }, server: { port: 5173, host: 0.0.0.0, proxy: { /api: { target: https://taotoken.net/api, changeOrigin: true, rewrite: (path) path.replace(/^\/api/, ) } } } })resolve.alias让指向src导入组件时可以写import Hello from /components/Hello.vue。server.proxy把/api开头的请求转发到 TaoToken 的 API 地址changeOrigin处理跨域rewrite去掉/api前缀。如果你用 TypeScript还需要在tsconfig.json里同步路径别名否则编辑器会报找不到模块{ compilerOptions: { baseUrl: ., paths: { /*: [src/*] } } }3.3 启动验证步骤配置写完后在项目根目录执行npm install npm run dev终端会输出类似VITE v5.x.x ready in 300 ms ➜ Local: http://localhost:5173/ ➜ Network: http://192.168.x.x:5173/ ➜ press h enter to show help浏览器打开http://localhost:5173/能看到 VUE3 默认页面就说明启动成功。如果端口被占用vite 会自动换到 5174注意看终端输出。4. 模板语法与 V3 指令实战从插值到 v-model 双向绑定4.1 模板插值语法在script setup里声明变量直接在template用{{ 变量名 }}使用template div{{ message }}/div /template script setup langts const message sh /script模板里支持条件运算、算术运算和 API 调用template div{{ message 0 ? 111 : 222 }}/div div{{ count 1 }}/div div{{ text.split() }}/div /template script setup langts const message: number 1 const count: number 10 const text: string 1234 /script注意模板表达式里不要写太复杂的逻辑超过一行的运算建议放到computed里。4.2 v-on 修饰符与冒泡处理v-on简写用来绑定事件。冒泡案例template div clickparent div click.stopchildchild/div /div /template script setup langts const child () { console.log(child) } const parent () { console.log(parent) } /script不加.stop时点击内层 div 会同时触发 child 和 parent。加上.stop后只触发 child。阻止表单提交用.preventtemplate form action/ button click.preventsubmit typesubmitsubmit/button /form /template script setup langts const submit () { console.log(submit) } /script4.3 v-bind 绑定 class 和 style普通数组写法template div :class[flag ? active : other, h]12323/div /template script setup langts const flag: boolean false /script style .active { color: red; } .other { color: blue; } .h { height: 300px; border: 1px solid #ccc; } /style对象写法配合 TS 类型template div :classflag{{ flag }}/div /template script setup langts type Cls { other: boolean h: boolean } const flag: Cls { other: false, h: true } /script绑定 styletemplate div :stylestyle2222/div /template script setup langts type Style { height: string color: string } const style: Style { height: 300px, color: blue } /script4.4 v-model 双向绑定template input v-modelmessage typetext / div{{ message }}/div /template script setup langts import { ref } from vue const message ref(v-model) /script输入框内容变化时message同步更新下面的 div 实时显示。v-model本质是:value加input的语法糖。4.5 其他常用指令速查v-text显示文本v-html展示富文本注意 XSS 风险不要渲染用户输入v-if/v-else-if/v-else控制元素真假 DOM 切换v-show通过 CSSdisplay切换v-for遍历元素。v-if和v-show的区别v-if会销毁和重建 DOMv-show只是切换显示频繁切换用v-show条件很少变用v-if。5. 常见报错排查401、local proxy failed、reading choices 怎么解5.1 401 Unauthorized请求 TaoToken API 返回 401通常是 Key 没带或带错。检查请求头Authorization: Bearer sk-xxxxxxxxKey 从 TaoToken 控制台的 API Keys 页面获取。注意不要有多余空格不要用单引号包裹。如果是在.env文件里配置变量名建议用VITE_前缀vite 才会暴露给客户端VITE_TAOTOKEN_KEYsk-xxxxxxxx代码里用import.meta.env.VITE_TAOTOKEN_KEY读取。5.2 local proxy failedvite 代理报local proxy failed或ECONNREFUSED先确认vite.config.ts里server.proxy.target写的是https://taotoken.net/api不是http。再确认本地网络能访问该地址。如果代理路径 rewrite 写错比如把/api替换成了空字符串但后端需要这个前缀也会 404。改完配置要重启npm run devvite 不会热更新配置文件。5.3 reading choices 报错调用模型接口时出现Cannot read properties of undefined (reading choices)说明返回结构和你解析的字段不匹配。先打印完整响应const res await fetch(/api/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${import.meta.env.VITE_TAOTOKEN_KEY} }, body: JSON.stringify({ model: gpt-4o-mini, messages: [{ role: user, content: 你好 }] }) }) const data await res.json() console.log(JSON.stringify(data, null, 2))确认data.choices存在后再取值。如果返回的是错误对象choices自然不存在先看data.error.message。5.4 OAuth 与 Codex auth.json 相关如果你在用 Codex 或类似工具认证信息可能写在auth.json里。出现 OAuth 相关报错时检查该文件里的base_url是否指向https://taotoken.net/apiapi_key是否和 TaoToken 控制台一致。三件套要写全Base URL、Key、Model ID缺一个都会失败。5.5 插件冲突导致类型全红script setup里所有变量都报「找不到名称」八成是 Vetur 和 Volar 同时开着。禁用 Vetur重启 VS Code。如果还不行在项目根目录建.vscode/settings.json{ vetur.validation.template: false, vue.server.hybridMode: true }6. 把本地调试 endpoint 改到 TaoToken 完成联调验证前面配置都跑通后最后一步是把请求真正发到 TaoToken验证整条链路。在src下新建api/chat.tsconst BASE_URL /api export async function chat(prompt: string) { const res await fetch(${BASE_URL}/v1/chat/completions, { method: POST, headers: { Content-Type: application/json, Authorization: Bearer ${import.meta.env.VITE_TAOTOKEN_KEY} }, body: JSON.stringify({ model: gpt-4o-mini, messages: [{ role: user, content: prompt }] }) }) if (!res.ok) { throw new Error(请求失败: ${res.status}) } const data await res.json() return data.choices[0].message.content }在组件里调用template div input v-modelinput typetext / button clicksend发送/button div{{ reply }}/div /div /template script setup langts import { ref } from vue import { chat } from /api/chat const input ref() const reply ref() const send async () { reply.value await chat(input.value) } /script启动npm run dev输入问题点发送能看到模型返回内容就说明联调成功。如果要在浏览器里直接对比不同模型的效果可以打开模型对话页面手动试如果准备长期做编码类 Agent 或批量调用建议看 Coding Plan 的额度方案Key 的创建和管理在 API Keys 页面接入细节参考接入文档。整条链路的关键就是把 Base URL、Key、Model ID 三件套对齐本地代理指向https://taotoken.net/api剩下的就是写业务代码了。