vuepress 项目必须局部安装，禁用全局安装；webstorm 需配置正确 node 路径、npm script 启动、启用 vue.js 插件并取消忽略 .vuepress/dist 目录。
VuePress 项目必须用局部安装，别碰全局安装
WebStorm 本身不干预包管理方式，但全局安装 vuepress 会导致版本混乱、插件识别失败、甚至 vuepress dev docs 报 Cannot find module 'vuepress'。官方自 VuePress 2.x 起就明确弃用全局模式，所有现代教程（包括 VuePress 官网和 2025 年最新文档）都只推荐局部安装。
实操建议：
- 在 WebStorm 终端里执行
npm install -D vuepress@next（或pnpm add -D vuepress@next），确保node_modules/.bin/vuepress存在 - 删掉系统级的全局命令：运行
npm uninstall -g vuepress，避免 WebStorm 的 Node.js 工具链误调用旧版（比如 0.14.x） - 检查 WebStorm 的「Node interpreter」设置（File → Settings → Languages & Frameworks → Node.js and NPM）：路径必须指向你项目所用的 Node 版本（≥18），而非全局 npm bin 目录
WebStorm 中正确配置 npm script 启动 dev server
直接在终端敲 npm run docs:dev 没问题，但 WebStorm 的 Run Configuration 能自动监听端口、热重载、并集成调试器——前提是脚本定义清晰且路径无歧义。
实操建议：
- 在
package.json的scripts里明确定义："docs:dev": "vuepress dev docs"（不是vuepress dev .或vuepress dev） - WebStorm → Run → Edit Configurations → + → npm → 填写：
• package.json：选项目根目录下的package.json
• Command：选docs:dev
• Working directory：自动填入项目根路径，别手动改成docs/或.vuepress/ - 勾选「Allow parallel run」，否则改完 config.js 后重启会卡住
- 启动后 WebStorm 底部会显示
http://localhost:8080，点击即可跳转；若端口被占，可在docs/.vuepress/config.js中加port: 8081，但需同步更新 Run Configuration 的「Port’字段
WebStorm 无法语法高亮或跳转 .md 文件里的 Vue 组件？
VuePress 的 Markdown 文件支持内联 Vue 语法（如 <badge text="beta"></badge>），但 WebStorm 默认把 .md 当纯文本，不会解析其中的 HTML 标签或 Vue 指令。
实操建议：
- 打开 Settings → Editor → File Types → Markdown → 在「Registered Patterns」里删掉
docs/**/*.md这类手动添加的排除项（如果有） - 关键一步：安装插件 Vue.js（Settings → Plugins → 搜索启用），它会让 WebStorm 把
.md文件当作「Vue-aware Markdown」处理 - 重启 WebStorm，再打开
docs/README.md，<badge></badge>就能跳转到组件定义，{{ $frontmatter.title }}也能提示类型 - 如果仍不生效，检查
docs/.vuepress/config.js是否导出的是defineUserConfig（VuePress 2+），而非旧式module.exports—— 后者会导致 WebStorm 无法推断上下文
build 后 dist 目录没出现在 WebStorm 项目视图里
vuepress build docs 默认输出到 docs/.vuepress/dist，但 WebStorm 默认忽略以 . 开头的目录，导致你找不到生成的 HTML 文件，也无法用内置服务器预览。
实操建议：
- 不要改输出路径（比如设成
dist/），因为 VuePress 的路由逻辑依赖默认结构；强行改会导致base配置错乱、链接 404 - Settings → Editor → File Types → Ignored files and folders → 删除
.vuepress（或至少删掉其中的dist） - 右键
docs/.vuepress/dist→ 「Reload from Disk」，让它立刻出现在项目树中 - 想本地预览 build 结果？右键
index.html→ 「Open in Browser」，或装插件「Simple HTTP Server」一键起服务
.vuepress/dist 必须从忽略列表里移除——这两处不动，其他配置全对也白搭。前端入门到VUE实战笔记：立即使用
在学习笔记中，你将探索 前端 的入门与实战技巧！
