Skip to content

本地开发 ​

四个站点的开发命令 ​

站点命令地址说明
pc-webnpm run devhttp://localhost:5173先跑 gen-pages.mjs 生成 HTML,再启动 Vite
mobile-webnpm run devhttp://localhost:5174--host 已开启,手机可连局域网 IP 调试
docs-sitenpm run devhttp://localhost:5173VitePress,改 Markdown 立即热更新
blog-sitenpm run devhttp://localhost:5173同样热更新,新增文章会自动出现在列表

端口冲突时用参数覆盖:

bash
npx vitepress dev --port 5178
npx vite --port 5175

电脑版的友好 URL 是怎么来的 ​

pc-web/vite.config.js 里有一段 friendlyUrls() 中间件,只在开发态生效:把 /text/word-counter/ 映射到 pages/text/word-counter/index.html。

这样开发时访问的路径和线上完全一致,避免出现「本地能点、线上 404」的情况。教育栏目和测算栏目路径更深,因此匹配规则按层级从深到浅排列:

/edu/junior/grade-7/math/  → pages/edu/junior/grade-7/math/index.html
/assess/cog/logic/         → pages/assess/cog/logic/index.html
/text/word-counter/        → pages/text/word-counter/index.html

手机版为什么能直接用电脑版组件 ​

mobile-web/vite.config.js 里做了三件事:

  1. @pc 别名指向 ../pc-web/src;
  2. dedupe: ['vue', ...] 保证只加载一份 Vue,否则会出现两个响应式系统;
  3. server.fs.allow 放开仓库上级目录,开发服务器才允许读 ../pc-web。

组件里 import 'vue' 会解析到手机版这一份依赖,而 @pc/tools/*.vue 里的相对导入仍指向 pc-web 内部文件。

改工具时的最小验证流程 ​

bash
cd pc-web
npm run gen        # 只重新生成 HTML,检查文案与 SEO 标签
npm run build      # 完整构建(含彩票数据抓取、postbuild 整理)
npm run preview    # 用构建产物本地验收

手机版验收:

bash
cd mobile-web
npm run build
npm run preview     # 注意 base='./',预览地址是 http://localhost:4173/

仓库里还有两个冒烟脚本(npm run smoke / npm run smoke:ui),用 Playwright 打开关键页面检查有没有报错,改完公共组件建议跑一遍。

常见开发问题 ​

现象原因处理
手机版报 Failed to resolve import '@pc/...'单独复制了 mobile-web 目录放回仓库同级位置
页面出现两套响应式、输入框不更新Vue 被解析成两份检查 dedupe 配置是否被改动
/text/xxx/ 本地 404没跑 gen-pages.mjsnpm run gen 或直接 npm run dev
VitePress 侧边栏不显示新页面没加到 config.mts 的 sidebar手动补链接,或放到已有分组目录下

文档随仓库一起更新,站点内容全部在浏览器本地运行。