[{"data":1,"prerenderedAt":684},["ShallowReactive",2],{"doc-page:\u002Fdocs\u002Flocal-setup":3},{"doc":4,"prev":642,"next":651,"resolvedType":8,"readingMinutes":146,"audience":658,"checklist":662,"related":666},{"path":5,"title":6,"description":7,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":12,"publishedAt":12,"icon":13,"body":14},"\u002Fdocs\u002Flocal-setup","本地运行与部署","使用 bun 安装、开发、构建与预览 DomiVault 的完整本地流程与排障指引","article",null,"dev-environment","开发环境","2026-03-10","i-carbon-code",{"type":15,"value":16,"toc":624},"minimark",[17,20,24,34,38,65,68,94,97,153,156,174,194,197,209,212,243,246,260,263,281,284,308,334,337,351,358,362,372,375,408,411,425,428,462,465,469,487,490,505,508,526,530,533,546,549,553,569,572,593,596,620],[18,19,6],"h1",{"id":6},[21,22,23],"p",{},"这篇文档面向两类场景：",[25,26,27,31],"ul",{},[28,29,30],"li",{},"你第一次把 DomiVault 跑起来",[28,32,33],{},"你要排查“本地能跑 \u002F 线上不能跑”的构建差异",[35,36,37],"h2",{"id":37},"环境要求",[25,39,40,47,53,59],{},[28,41,42,46],{},[43,44,45],"strong",{},"推荐","：Node.js 22 LTS",[28,48,49,52],{},[43,50,51],{},"最低","：Node.js 18+",[28,54,55,58],{},[43,56,57],{},"包管理器","：bun 1.x",[28,60,61,64],{},[43,62,63],{},"必备工具","：Git",[21,66,67],{},"如果你主要在 Windows 上开发，建议配合：",[25,69,70,77,83],{},[28,71,72],{},[73,74,76],"a",{"href":75},"\u002Fdocs\u002Fdev-environment","Windows 开发环境搭建",[28,78,79],{},[73,80,82],{"href":81},"\u002Fdocs\u002Fwsl-setup","WSL 安装与配置",[28,84,85,89,90],{},[73,86,88],{"href":87},"\u002Fdocs\u002Fvolta-guide","Volta Node 版本管理"," 或 ",[73,91,93],{"href":92},"\u002Fdocs\u002Fmise-guide","mise 多语言版本管理",[35,95,96],{"id":96},"第一次初始化",[98,99,104],"pre",{"className":100,"code":101,"language":102,"meta":103,"style":103},"language-bash shiki shiki-themes github-light github-dark","git clone \u003Crepo-url>\ncd domivault\nbun install\n","bash","",[105,106,107,134,144],"code",{"__ignoreMap":103},[108,109,112,116,120,124,127,131],"span",{"class":110,"line":111},"line",1,[108,113,115],{"class":114},"sScJk","git",[108,117,119],{"class":118},"sZZnC"," clone",[108,121,123],{"class":122},"szBVR"," \u003C",[108,125,126],{"class":118},"repo-ur",[108,128,130],{"class":129},"sVt8B","l",[108,132,133],{"class":122},">\n",[108,135,137,141],{"class":110,"line":136},2,[108,138,140],{"class":139},"sj4cs","cd",[108,142,143],{"class":118}," domivault\n",[108,145,147,150],{"class":110,"line":146},3,[108,148,149],{"class":114},"bun",[108,151,152],{"class":118}," install\n",[21,154,155],{},"安装完成后，建议立即做一次类型检查：",[98,157,159],{"className":100,"code":158,"language":102,"meta":103,"style":103},"bun x nuxi typecheck\n",[105,160,161],{"__ignoreMap":103},[108,162,163,165,168,171],{"class":110,"line":111},[108,164,149],{"class":114},[108,166,167],{"class":118}," x",[108,169,170],{"class":118}," nuxi",[108,172,173],{"class":118}," typecheck\n",[175,176,177],"blockquote",{},[21,178,179,180,182,183,186,187,186,190,193],{},"本仓库统一使用 ",[105,181,149],{},"，不要混用 ",[105,184,185],{},"npm","、",[105,188,189],{},"pnpm",[105,191,192],{},"yarn","，避免锁文件和依赖树漂移。",[35,195,196],{"id":196},"开发模式",[98,198,200],{"className":100,"code":199,"language":102,"meta":103,"style":103},"bun dev\n",[105,201,202],{"__ignoreMap":103},[108,203,204,206],{"class":110,"line":111},[108,205,149],{"class":114},[108,207,208],{"class":118}," dev\n",[21,210,211],{},"默认地址：",[25,213,214,222,229,236],{},[28,215,216,217],{},"页面：",[73,218,219],{"href":219,"rel":220},"http:\u002F\u002Flocalhost:3000",[221],"nofollow",[28,223,224,225],{},"首页摘要接口：",[73,226,227],{"href":227,"rel":228},"http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fhome\u002Fsummary",[221],[28,230,231,232],{},"文档摘要接口：",[73,233,234],{"href":234,"rel":235},"http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fdocs\u002Fsummary",[221],[28,237,238,239],{},"搜索索引接口：",[73,240,241],{"href":241,"rel":242},"http:\u002F\u002Flocalhost:3000\u002Fapi\u002Fdocs\u002Fsearch-index",[221],[21,244,245],{},"开发模式下的特点：",[25,247,248,254,257],{},[28,249,250,253],{},[105,251,252],{},"content\u002Fdocs\u002F*.md"," 改动后会自动热更新",[28,255,256],{},"Nuxt 页面和 API 路由会一起重建",[28,258,259],{},"适合调试导航、搜索、文档内容和页面样式",[21,261,262],{},"如果 3000 端口被占用：",[98,264,266],{"className":100,"code":265,"language":102,"meta":103,"style":103},"bun dev --port 3001\n",[105,267,268],{"__ignoreMap":103},[108,269,270,272,275,278],{"class":110,"line":111},[108,271,149],{"class":114},[108,273,274],{"class":118}," dev",[108,276,277],{"class":139}," --port",[108,279,280],{"class":139}," 3001\n",[35,282,283],{"id":283},"构建与预览",[98,285,287],{"className":100,"code":286,"language":102,"meta":103,"style":103},"bun run build\nbun run preview\n",[105,288,289,299],{"__ignoreMap":103},[108,290,291,293,296],{"class":110,"line":111},[108,292,149],{"class":114},[108,294,295],{"class":118}," run",[108,297,298],{"class":118}," build\n",[108,300,301,303,305],{"class":110,"line":136},[108,302,149],{"class":114},[108,304,295],{"class":118},[108,306,307],{"class":118}," preview\n",[25,309,310,319,325],{},[28,311,312,315,316],{},[105,313,314],{},"build"," 会生成生产环境产物，输出到 ",[105,317,318],{},"dist\u002F",[28,320,321,324],{},[105,322,323],{},"preview"," 用来本地模拟生产包访问效果",[28,326,327,328,330,331],{},"如果你要排查 Cloudflare Pages 问题，优先用 ",[105,329,314],{}," 而不是只跑 ",[105,332,333],{},"dev",[35,335,336],{"id":336},"静态生成",[98,338,340],{"className":100,"code":339,"language":102,"meta":103,"style":103},"bun run generate\n",[105,341,342],{"__ignoreMap":103},[108,343,344,346,348],{"class":110,"line":111},[108,345,149],{"class":114},[108,347,295],{"class":118},[108,349,350],{"class":118}," generate\n",[21,352,353,354,357],{},"适合纯静态导出场景；但本仓库包含服务端摘要与搜索接口，因此日常仍以 ",[105,355,356],{},"bun run build"," 为主。",[35,359,361],{"id":360},"与-cloudflare-pages-保持一致","与 Cloudflare Pages 保持一致",[21,363,364,365,368,369,371],{},"这个项目最终部署在 Cloudflare Pages。本地如果只跑 ",[105,366,367],{},"bun install"," + ",[105,370,356],{},"，有时还不够暴露平台差异。",[21,373,374],{},"建议在排查部署问题时，再补跑一次：",[98,376,378],{"className":100,"code":377,"language":102,"meta":103,"style":103},"npm install --package-lock=false\nbun x nuxi typecheck\nbun run build\n",[105,379,380,390,400],{"__ignoreMap":103},[108,381,382,384,387],{"class":110,"line":111},[108,383,185],{"class":114},[108,385,386],{"class":118}," install",[108,388,389],{"class":139}," --package-lock=false\n",[108,391,392,394,396,398],{"class":110,"line":136},[108,393,149],{"class":114},[108,395,167],{"class":118},[108,397,170],{"class":118},[108,399,173],{"class":118},[108,401,402,404,406],{"class":110,"line":146},[108,403,149],{"class":114},[108,405,295],{"class":118},[108,407,298],{"class":118},[21,409,410],{},"这样更容易提前发现：",[25,412,413,419,422],{},[28,414,415,418],{},[105,416,417],{},"npm install"," 的 peer 依赖冲突",[28,420,421],{},"Nuxt Content \u002F Nitro 在 CI 环境下的构建差异",[28,423,424],{},"Cloudflare 安装链路和本地 bun 安装链路不一致的问题",[35,426,427],{"id":427},"修改文档时的建议流程",[429,430,431,446,449,452,459],"ol",{},[28,432,433,434,186,437,186,440,186,443],{},"先补全 frontmatter：",[105,435,436],{},"title",[105,438,439],{},"description",[105,441,442],{},"date",[105,444,445],{},"category",[28,447,448],{},"再写正文结构，至少保证有清晰的小节",[28,450,451],{},"添加站内互链，减少“孤立页面”",[28,453,454,455],{},"如有必要，补到 ",[73,456,458],{"href":457},"\u002Fdocs\u002Fnavigation","站内导航与索引",[28,460,461],{},"提交前重新构建，确认内容能进入产物",[35,463,464],{"id":464},"常见问题",[466,467,468],"h3",{"id":468},"依赖安装失败",[25,470,471,474,477],{},[28,472,473],{},"先确认 Node 版本是否过低",[28,475,476],{},"再确认 bun 是否在 PATH 中",[28,478,479,480,89,483,486],{},"如果误生成了 ",[105,481,482],{},"package-lock.json",[105,484,485],{},"pnpm-lock.yaml","，请删掉后重装",[466,488,489],{"id":489},"页面打不开",[25,491,492,495,498],{},[28,493,494],{},"看终端是否真的启动成功",[28,496,497],{},"检查 3000 端口是否被别的程序占用",[28,499,500,501,504],{},"用 ",[105,502,503],{},"bun dev --port 3001"," 换端口验证",[466,506,507],{"id":507},"文档改了但页面没刷新",[25,509,510,517,520],{},[28,511,512,513,516],{},"确认修改的是 ",[105,514,515],{},"content\u002Fdocs"," 下的文件",[28,518,519],{},"观察终端是否出现内容重建日志",[28,521,522,523],{},"不行就重启 ",[105,524,525],{},"bun dev",[466,527,529],{"id":528},"本地构建通过线上部署失败","本地构建通过，线上部署失败",[21,531,532],{},"优先复现：",[98,534,536],{"className":100,"code":535,"language":102,"meta":103,"style":103},"npm install --package-lock=false\n",[105,537,538],{"__ignoreMap":103},[108,539,540,542,544],{"class":110,"line":111},[108,541,185],{"class":114},[108,543,386],{"class":118},[108,545,389],{"class":139},[21,547,548],{},"Cloudflare Pages 的安装阶段走的是 npm 解析链路，本地只用 bun 有时复现不出问题。",[466,550,552],{"id":551},"接口返回-404","接口返回 404",[25,554,555,562],{},[28,556,557,558,89,560],{},"先确认你跑的是 ",[105,559,525],{},[105,561,356],{},[28,563,564,565,568],{},"如果你只用了 ",[105,566,567],{},"generate","，部分服务端接口验证会失真",[35,570,571],{"id":571},"提交前检查",[25,573,574,579,585,590],{},[28,575,576,577],{},"安装：",[105,578,367],{},[28,580,581,582],{},"类型：",[105,583,584],{},"bun x nuxi typecheck",[28,586,587,588],{},"构建：",[105,589,356],{},[28,591,592],{},"内容：frontmatter、站内互链、外链、表格格式",[35,594,595],{"id":595},"相关文档",[25,597,598,602,608,614],{},[28,599,600],{},[73,601,76],{"href":75},[28,603,604],{},[73,605,607],{"href":606},"\u002Fdocs\u002Fcloudflare-pages-deploy","Cloudflare Pages 部署指南",[28,609,610],{},[73,611,613],{"href":612},"\u002Fdocs\u002Fnuxt-vue-notes","Nuxt \u002F Vue 笔记",[28,615,616],{},[73,617,619],{"href":618},"\u002Fdocs\u002Fai-agents-cli","AI 终端代理工具",[621,622,623],"style",{},"html pre.shiki code .sScJk, html code.shiki .sScJk{--shiki-default:#6F42C1;--shiki-dark:#B392F0}html pre.shiki code .sZZnC, html code.shiki .sZZnC{--shiki-default:#032F62;--shiki-dark:#9ECBFF}html pre.shiki code .szBVR, html code.shiki .szBVR{--shiki-default:#D73A49;--shiki-dark:#F97583}html pre.shiki code .sVt8B, html code.shiki .sVt8B{--shiki-default:#24292E;--shiki-dark:#E1E4E8}html pre.shiki code .sj4cs, html code.shiki .sj4cs{--shiki-default:#005CC5;--shiki-dark:#79B8FF}html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}html.dark .shiki span {color: var(--shiki-dark);background: var(--shiki-dark-bg);font-style: var(--shiki-dark-font-style);font-weight: var(--shiki-dark-font-weight);text-decoration: var(--shiki-dark-text-decoration);}",{"title":103,"searchDepth":136,"depth":136,"links":625},[626,627,628,629,630,631,632,633,640,641],{"id":37,"depth":136,"text":37},{"id":96,"depth":136,"text":96},{"id":196,"depth":136,"text":196},{"id":283,"depth":136,"text":283},{"id":336,"depth":136,"text":336},{"id":360,"depth":136,"text":361},{"id":427,"depth":136,"text":427},{"id":464,"depth":136,"text":464,"children":634},[635,636,637,638,639],{"id":468,"depth":146,"text":468},{"id":489,"depth":146,"text":489},{"id":507,"depth":146,"text":507},{"id":528,"depth":146,"text":529},{"id":551,"depth":146,"text":552},{"id":571,"depth":136,"text":571},{"id":595,"depth":136,"text":595},{"path":643,"title":644,"description":645,"docType":8,"resourceKind":9,"categoryId":646,"categoryLabel":647,"updatedAt":648,"publishedAt":649,"icon":650},"\u002Fdocs\u002Fnetwork-proxy","网络工具记录","内网穿透、网络诊断、网站测速与安全检查工具记录","network-security","网络与安全","2026-04-11","2025-10-11","i-carbon-network-4",{"path":652,"title":653,"description":654,"docType":8,"resourceKind":9,"categoryId":655,"categoryLabel":656,"updatedAt":12,"publishedAt":12,"icon":657},"\u002Fdocs\u002Fbrowser-extensions","浏览器扩展推荐","开发调试、效率提升、隐私安全与阅读增强场景下的浏览器扩展选择建议","online-tools","在线工具","i-carbon-tool-box",[659,660,661],"希望把零散经验整理成长期可复用工作流的人","正在搭建开发环境、统一工具链或排查构建问题的开发者","希望阅读时顺手建立自己的操作清单或收藏体系的人",[663,664,665],"先浏览标题、摘要和目录，带着问题阅读会更高效","确认本机 Node、包管理器、终端和仓库依赖版本是否一致","如果页面里提到相关文档，尽量一起打开对照，效果通常更完整",[667,670,675,680],{"path":87,"title":88,"description":668,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":669,"publishedAt":669,"icon":13},"使用 Volta 管理 Node.js、npm、pnpm 和 Yarn，并在项目中固定 JavaScript 工具链版本","2026-03-08",{"path":671,"title":672,"description":673,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":674,"publishedAt":674,"icon":13},"\u002Fdocs\u002Fpnpm-monorepo","pnpm 与 Monorepo","pnpm 使用技巧、workspace 配置、Monorepo 项目管理与 Turborepo","2026-02-28",{"path":676,"title":677,"description":678,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":679,"publishedAt":679,"icon":13},"\u002Fdocs\u002Fenv-variables","环境变量管理","dotenv 配置、各平台环境变量设置、.env 文件规范与安全实践","2026-02-27",{"path":681,"title":682,"description":683,"docType":8,"resourceKind":9,"categoryId":10,"categoryLabel":11,"updatedAt":679,"publishedAt":679,"icon":13},"\u002Fdocs\u002Fapi-testing","API 测试与调试","curl、HTTPie、Postman、Bruno 等 API 测试工具与常用技巧",1776215713418]