Hyde Blog

主题

Hyde2025-03-29 23:55:39Teek
1121
5.8m
Get...

构建 ​

打包 ​

docs:build 脚本将构建你的站点，并将所有静态资源输出到 docs/.vitepress/dist 目录中。使用以下命令运行它：

sh
$ pnpm docs:build
sh
$ npm docs:build
sh

CSS 语法警告 ​

  • VitePress 构建时出现的 CSS 语法警告,原因是<style>标签内第8412行的分号问题 警告如下
shell
⠋ building client + server bundles...warnings when minifying css:
▲ [WARNING] Unexpected ";" [css-syntax-error]

    <stdin>:8412:1:
      8412 │ };
           ╵  ^

解决方法 ​

  • 在docs\index.md文件中,删除index.md文件中分号;
md
:root {
animation: rainbow 12s linear infinite;
}; // 删除这里的分号

vite过大的警告 ​

  • 打包时出现如下警告
shell
(!) Some chunks are larger than 500 kB after minification. Consider:
- Using dynamic import() to code-split the application
- Use build.rollupOptions.output.manualChunks to improve chunking: https://rollupjs.org/configuration-options/#output-manualchunks
- Adjust chunk size limit for this warning via build.chunkSizeWarningLimit.

警告

提示你的内容太大了，打包后的任意文件超出了 500KB，希望你能优化下,要么 md 文档内容写少点,当然这不现实

解决方法 ​

  • 在docs\.vitepress\config.mts,添加如下配置
ts
export default defineConfig({
    vite: {
     //其他配置项
    build: {
      chunkSizeWarningLimit: 1500, // 限制警告的块大小
    },
  },
})

侧边栏插件警告 ​

  • 启动运行或者构建打包时出现如下警告
sh
21:07:49 [vitepress-plugin-sidebar-resolve v1.0.8] 该目录 'D:\code\teek-hyde\docs\nav' 内部没有任何文件或文件序号出错，将忽略生成对应侧边栏

解决方法 ​

ts
// docs\.vitepress\config.mts
vitePlugins: {
  sidebarOption: {
    initItems: false,
    collapsed: true,
    ignoreList: ["nav"], //忽略的文件夹和文件
  },
  autoFrontmatter: true,
},

SSR 构建警告 ​

  • 构建控制台日志
sh
ReferenceError: document is not defined
    at setup (file:///D:/code/teek-hyde/docs/.vitepress/.temp/app.js:2:19683)
    at Je.setup (file:///D:/code/teek-hyde/docs/.vitepress/.temp/app.js:2:20133)
    at callWithErrorHandling (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:86:19)
    at setupStatefulComponent (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:6292:25)
    at setupComponent (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:6279:36)
    at renderComponentVNode (D:\code\teek-hyde\node_modules\.pnpm\@vue+server-renderer@3.5.13_vue@3.5.13_typescript@5.8.3_\node_modules\@vue\server-renderer\dist\server-renderer.cjs.prod.js:376:15)
    at renderVNode (D:\code\teek-hyde\node_modules\.pnpm\@vue+server-renderer@3.5.13_vue@3.5.13_typescript@5.8.3_\node_modules\@vue\server-renderer\dist\server-renderer.cjs.prod.js:507:14)
    at renderVNodeChildren (D:\code\teek-hyde\node_modules\.pnpm\@vue+server-renderer@3.5.13_vue@3.5.13_typescript@5.8.3_\node_modules\@vue\server-renderer\dist\server-renderer.cjs.prod.js:523:5)
    at renderVNode (D:\code\teek-hyde\node_modules\.pnpm\@vue+server-renderer@3.5.13_vue@3.5.13_typescript@5.8.3_\node_modules\@vue\server-renderer\dist\server-renderer.cjs.prod.js:495:7)
    at renderVNodeChildren (D:\code\teek-hyde\node_modules\.pnpm\@vue+server-renderer@3.5.13_vue@3.5.13_typescript@5.8.3_\node_modules\@vue\server-renderer\dist\server-renderer.cjs.prod.js:523:5)
ReferenceError: localStorage is not defined
    at a.value.useStorage.o.immediate (file:///D:/code/teek-hyde/docs/.vitepress/.temp/theme.CDc3yOIy.js:2:1272097)
    at callWithErrorHandling (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:86:19)
    at callWithAsyncErrorHandling (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:93:17)
    at baseWatchOptions.call (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:4810:47)
    at job (D:\code\teek-hyde\node_modules\.pnpm\@vue+reactivity@3.5.13\node_modules\@vue\reactivity\dist\reactivity.cjs.prod.js:1661:18)
    at Object.watch (D:\code\teek-hyde\node_modules\.pnpm\@vue+reactivity@3.5.13\node_modules\@vue\reactivity\dist\reactivity.cjs.prod.js:1693:7)
    at doWatch (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:4838:34)
    at watch (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:4789:10)
    at setup (file:///D:/code/teek-hyde/docs/.vitepress/.temp/theme.CDc3yOIy.js:2:1272049)
    at callWithErrorHandling (D:\code\teek-hyde\node_modules\.pnpm\@vue+runtime-core@3.5.13\node_modules\@vue\runtime-core\dist\runtime-core.cjs.prod.js:86:19)
省略....
  • 原因:

从错误日志看，构建过程中出现了两个主要问题：localStorage is not defined 和 document is not defined。这些错误通常发生在服务端渲染(SSR)或静态站点生成(SSG)环境中，因为 Node.js 运行时没有浏览器环境中的全局对象。

解决方案 ​

某个组件需要在挂载时启用，具体哪个组件忘记了，最新模板已修复

打包进程卡住 ​

bash
⠏ building client + server bundles...llmstxt »   Skipping LLMs docs generation in SSR build

✓ building client + server bundles...

✓ rendering pages...

build complete in 117.13s.
#在这个地方就会卡住，不会继续执行下去

解决方案 ​

在docs\.vitepress\theme\config\teekConfig.ts中把tryRequest设置为false

ts
// 博客基础配置
const teekBlogCommonConfig: TeekConfig = {
  docAnalysis: {
    tryRequest: false, //重试次数，仅当 tryRequest 为 true 时有效
  },
};
最近更新