webstorm运行vitepress dev失败需设working directory为$projectfiledir$/docs，因vitepress要求命令在docs目录执行；启动后白屏或404需检查base配置、index.md位置及文件路径映射；config.mts类型不识别应手动导入defineconfig并确认ts版本匹配。
WebStorm里直接跑vitepress dev失败？先确认工作目录
很多人在 WebStorm 里点运行按钮后报错 ERR_MODULE_NOT_FOUND 或提示找不到 .vitepress/config.mts，根本原因是 WebStorm 默认以项目根目录为工作路径，但 VitePress 要求命令必须在 docs 目录下执行（除非你显式设置了 srcDir）。
解决方法很简单：打开 Run > Edit Configurations...，找到你的 npm script 配置，在 Working directory 栏填入 $ProjectFileDir$/docs。不是 ./docs，也不是留空——必须是绝对路径变量。
- 如果初始化时选了
./而非./docs，那配置目录就在项目根下，此时工作目录应设为$ProjectFileDir$ -
package.json里的"docs:dev": "vitepress dev"这条脚本本身不带路径参数，完全依赖工作目录 - 别信 WebStorm 自动推导的路径，它常把
node_modules/.bin/vitepress当成入口，绕过项目上下文
vitepress dev 启动后页面空白或 404？检查 base 和文件位置
启动成功但浏览器打开是白屏或 404，大概率是路由和文件映射没对上。VitePress 默认把 docs/index.md 当首页，且所有链接都按 base 前缀拼接。
比如你在 docs/posts/2024-01-01-hello.md 写了文章，想通过 /posts/hello 访问，就必须确保：themeConfig.sidebar 里配的路径是 /posts/hello（不带 .md），同时该文件真实存在于 docs/posts/2024-01-01-hello.md。
-
base设为'/'是最安全的默认值；设成'/blog/'后，所有链接、public资源路径、甚至 GitHub Pages 的CNAME都要同步调整 -
index.md必须在docs目录下，不能放在子目录里——否则首页直接 404 - WebStorm 的「Preview」插件（如 Markdown Preview Enhanced）会干扰 VitePress 的热更新，关掉它再试
WebStorm自动导入defineConfig失败？TypeScript类型不识别
在 .vitepress/config.mts 里写 defineConfig({ ... }) 时，WebStorm 提示 “Unresolved function” 或红色波浪线，不是代码错，而是 TS 类型没加载进来。
原因：VitePress 的类型定义没被 WebStorm 的 TS 服务识别。手动触发一次类型获取即可：
- 打开
.vitepress/config.mts，光标停在defineConfig上，按Alt+Enter（macOS 是Option+Enter），选 “Import symbol from 'vitepress'” - 如果没弹选项，去
File > Settings > Languages & Frameworks > TypeScript，确认 “TypeScript language service” 已启用，且版本匹配你装的vitepress（比如 v1.3.x 对应 TS 5.0+） - 删掉
node_modules/.vitepress缓存目录（它有时会锁死旧类型），重启 WebStorm
改完config.mts不生效？热更新卡在“reloading config...”
WebStorm 里保存 config.mts 后，终端卡在 “reloading config...” 几秒不动，甚至要 Ctrl+C 重开，说明 VitePress 的 config watcher 没监听到变更，或者 WebStorm 的文件系统事件没透传过去。
这不是 bug，是 Electron + WebStorm 文件监视器的已知摩擦点。临时解法比等修复更快：
- 保存后立刻在终端手动敲
Ctrl+C终止当前进程，再执行pnpm docs:dev（不要用 WebStorm 的绿色三角按钮重跑） - 关闭 WebStorm 的 “Safe write” 选项：
Settings > Appearance & Behavior > System Settings，取消勾选 “Use ‘safe write’ (save changes to a temporary file first)” - Mac 用户注意：如果用了 iCloud 同步
docs目录，iCloud Drive 的延迟写入会导致 VitePress 读到旧文件，把项目移到本地磁盘非同步目录下
真正麻烦的不是配置本身，而是 WebStorm 和 VitePress 在文件系统层的“信任问题”——一个信 inotify，一个信 fs.watch，中间差半拍就卡住。动手改路径、关 Safe write、手动重启，比调半天 IDE 设置更省时间。
