企业官网建设流程全解析

1. 问题现象与背景分析

最近在VitePress项目打包时遇到一个典型错误："window is undefined"。这个报错通常发生在从开发环境切换到生产环境构建时，本质上是浏览器API与Node.js运行时环境差异导致的兼容性问题。

VitePress作为基于Vite的静态站点生成器，在开发模式下运行于浏览器环境，此时window对象自然存在；而执行vitepress build命令时，构建过程实际上是在Node.js环境中完成的。Node.js作为服务端JavaScript运行时，默认不存在浏览器特有的window、document等全局对象，这就导致了代码中直接引用这些对象时抛出未定义错误。

2. 核心问题诊断

2.1 环境差异解析

开发环境与生产环境的关键区别：

2.2 典型报错场景

以下代码在构建时会触发错误：

// 直接访问window对象 const userAgent = window.navigator.userAgent

// 在setup脚本中直接使用DOM API onMounted(() => { document.title = '新标题' })

3. 解决方案与实现

3.1 条件判断法（推荐）

最稳妥的方式是通过环境判断保护浏览器API调用：

import { onMounted } from 'vue' onMounted(() => { if (typeof window !== 'undefined') { // 安全的浏览器环境操作 window.scrollTo(0, 0) } })

3.2 动态导入策略

对于非首屏必需的浏览器特性，可采用动态导入：

const loadBrowserModule = async () => { if (typeof window !== 'undefined') { const module = await import('./browser-only-module') module.init() } }

3.3 构建时环境变量

通过Vite的环境变量区分运行环境：

// vite.config.js export default defineConfig({ define: { __BROWSER__: process.env.NODE_ENV === 'development' } }) // 组件中使用 if (__BROWSER__) { // 浏览器专用代码 }

4. 深度优化方案

4.1 自定义客户端入口

创建单独的客户端入口文件client.js：

// .vitepress/client.js import { defineClientConfig } from 'vitepress' export default defineClientConfig({ enhance({ app, router, siteData }) { if (import.meta.env.SSR) return // 客户端初始化逻辑 console.log('Running in browser') } })

4.2 SSR兼容组件

对于必须区分环境的组件，创建适配器组件：

<!-- BrowserComponent.vue --> <script setup> import { ref, onMounted } from 'vue' const isBrowser = ref(false) onMounted(() => { isBrowser.value = true }) </script> <template> <slot v-if="isBrowser" /> <div v-else class="ssr-placeholder" /> </template>

5. 常见问题排查

5.1 第三方库兼容问题

当使用含有浏览器API的第三方库时，推荐解决方案：

1. 使用动态导入：

const loadLib = async () => { if (!import.meta.env.SSR) { const lib = await import('browser-only-lib') lib.init() } }

2. 配置vite排除：

// vite.config.js export default { ssr: { noExternal: ['browser-only-package'] } }

5.2 样式表闪动问题

解决策略：

/* 添加SSR过渡样式 */ .ssr-hidden { visibility: hidden; } .client-only { visibility: visible; }

配合客户端脚本：

onMounted(() => { document.body.classList.remove('ssr-hidden') document.body.classList.add('client-only') })

6. 高级构建配置

6.1 自定义SSR构建

在.vitepress/config.js中扩展构建配置：

export default { vite: { ssr: { target: 'node', format: 'cjs', noExternal: ['需要外部化的包'] } } }

6.2 环境变量注入

安全注入环境变量：

// vite.config.js export default { define: { __SUPPORT_EMAIL__: JSON.stringify('contact@example.com') } }

7. 性能优化实践

7.1 关键资源预加载

配置客户端入口：

// client.js export default defineClientConfig({ setup() { if (import.meta.env.SSR) return const preload = url => { const link = document.createElement('link') link.rel = 'preload' link.href = url document.head.appendChild(link) } preload('/fonts/important.woff2') } })

7.2 异步组件优化

<script setup> const AsyncComp = import.meta.env.SSR ? defineAsyncComponent(() => import('./SSRFallback.vue')) : defineAsyncComponent(() => import('./RealComponent.vue')) </script>

8. 调试技巧

8.1 SSR错误追踪

在vitepress build命令中添加调试参数：

DEBUG=vite:transform vitepress build

8.2 构建产物分析

安装分析插件：

npm install rollup-plugin-visualizer -D

配置vite：

import { visualizer } from 'rollup-plugin-visualizer' export default { plugins: [ visualizer({ open: true }) ] }

9. 架构设计建议

9.1 分层架构设计

推荐的项目结构：

components/ browser/ BrowserOnlyComponent.vue shared/ CommonComponent.vue ssr/ SSRComponent.vue

9.2 类型安全增强

创建环境类型声明：

// env.d.ts declare const __BROWSER__: boolean interface ImportMeta { readonly env: { SSR: boolean } }

10. 持续集成方案

10.1 构建验证脚本

创建check-build.js：

const { execSync } = require('child_process') try { execSync('vitepress build', { stdio: 'inherit' }) console.log('✅ Build successful') } catch (err) { console.error('❌ Build failed') process.exit(1) }

10.2 自动化测试集成

示例测试配置：

// test/browser.test.js describe('Browser环境测试', () => { beforeAll(async () => { await page.goto('http://localhost:3000') }) it('应该正确加载页面', async () => { await expect(page).toHaveText('h1', '欢迎') }) })

在实际项目中，建议结合项目具体需求选择最适合的解决方案。对于简单的文档站点，条件判断法已经足够；而复杂的应用则需要考虑更完善的环境隔离方案。关键是要始终保持对运行环境的清醒认知，避免在服务端渲染阶段访问浏览器专属API。