VUE项目部署IIS服务器手册

IIS部署Vue项目完整手册

目录

1. 基础概念
2. 准备工作
3. Vue项目构建
4. web.config详解
5. IIS部署步骤
6. 不同场景配置
7. 常见问题
8. 实用配置模板

---

基础概念

Vue单页应用（SPA）工作原理

重要理解：Vue项目是单页应用，这意味着：

• 物理层面：整个项目只有一个HTML文件（index.html）

• 逻辑层面：用户看到多个"页面"，实际上是JavaScript动态切换内容

• 路由处理：所有路由跳转都由Vue Router在前端处理

  当用户直接访问 http://yoursite.com/about 时：

  1. 没有web.config：

     用户访问 /about → IIS寻找 about.html 文件 → 找不到 → 404错误
     

  2. 有web.config重写规则：

     用户访问 /about → IIS找不到about.html → web.config规则生效 → 返回index.html → Vue Router接管，显示about页面
     

用户看到的：
/home     -> 首页
/about    -> 关于页面
/products -> 产品页面
/contact  -> 联系页面

实际服务器文件：
dist/
├── index.html  ← 只有这一个HTML文件！
├── css/
├── js/
└── assets/

路由模式对比

路由模式	URL格式	IIS配置需求	说明
Hash模式	/#/home	无需配置	兼容性好，但URL不美观
History模式	/home	必须配置	URL美观，需要服务器支持

---

准备工作

环境要求

• Node.js：版本 14+
• Vue CLI：最新版本
• IIS：Windows Server 2016+ 或 Windows 10+
• URL Rewrite模块：必须安装

安装Vue CLI

# 全局安装Vue CLI
npm install -g @vue/cli

# 验证安装
vue --version

检查IIS URL Rewrite

1. 打开IIS管理器
2. 选择服务器节点
3. 查看是否有"URL 重写"图标
4. 如果没有，请下载安装：URL Rewrite 2.1

---

Vue项目构建

创建新项目

# 创建项目
vue create my-vue-project

# 选择配置
? Please pick a preset: 
  Default ([Vue 3] babel, eslint) 
❯ Default ([Vue 2] babel, eslint) 
  Manually select features

# 进入项目目录
cd my-vue-project

# 开发测试
npm run serve

构建生产版本

# 构建项目
npm run build

# 构建完成后会生成dist文件夹
dist/
├── index.html
├── css/
├── js/
├── img/
└── favicon.ico

配置自动生成web.config

方法1：在public文件夹中创建（推荐）

在项目的 public/ 文件夹中创建 web.config 文件，构建时会自动复制到 dist/。

方法2：在vue.config.js中配置

// vue.config.js
const { defineConfig } = require('@vue/cli-service')

module.exports = defineConfig({
  transpileDependencies: true,
  
  // 配置基础路径（如果部署在子目录）
  publicPath: process.env.NODE_ENV === 'production' ? '/myapp/' : '/',
  
  // 自定义构建过程
  configureWebpack: {
    plugins: [
      {
        apply: (compiler) => {
          compiler.hooks.emit.tapAsync('CopyWebConfig', (compilation, callback) => {
            const webConfigContent = `

  
    
      
        
          
          
            
            
          
          
        
      
    
  
`;
            
            compilation.assets['web.config'] = {
              source: () => webConfigContent,
              size: () => webConfigContent.length
            };
            callback();
          });
        }
      }
    ]
  }
})

---

web.config详解

核心重写规则解析

<rule name="Handle History Mode and hash fallback" stopProcessing="true">
  <match url="(.*)" />  
  <conditions logicalGrouping="MatchAll">
    
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
    
    <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
  conditions>
  
  <action type="Rewrite" url="/" />
rule>

翻译成人话：如果用户访问的不是真实存在的文件或文件夹，就给他返回首页（index.html），让Vue Router来处理。

执行逻辑：

1. 用户访问 /about

2. IIS检查服务器上是否有 about.html 文件 → 没有

3. IIS检查服务器上是否有 about/ 文件夹 → 没有

4. 触发重写规则，返回 index.html

5. Vue Router接管，显示about页面内容

   无论您的Vue项目有多少个界面，这个重写规则都不用变！

   因为：

   • 10个界面 → 还是只有1个index.html
   • 100个界面 → 还是只有1个index.html
   • 1000个界面 → 还是只有1个index.html

   所有界面的切换都是Vue Router在前端JavaScript中处理的。

重要概念

• stopProcessing=“true”：匹配到此规则后停止处理后续规则
• negate=“true”：条件取反，即"不是文件"的意思
• {REQUEST_FILENAME}：IIS服务器变量，表示请求的文件路径

---

IIS部署步骤

第一步：复制文件

# 将dist文件夹内容复制到IIS目录
# 例如：C:\inetpub\wwwroot\myvueapp\

第二步：创建IIS网站

1. 打开IIS管理器
2. 右键"网站" → “添加网站”
3. 配置网站信息：
   • 网站名称：Vue-App
   • 物理路径：C:\inetpub\wwwroot\myvueapp
   • 端口：80 或其他可用端口
   • 主机名：（可选）

第三步：配置应用程序池

1. 选择应用程序池
2. 高级设置：
   • .NET CLR版本：无托管代码
   • 托管管道模式：集成
   • 启用32位应用程序：False

第四步：设置权限

1. 右键网站文件夹
2. 属性 → 安全
3. 添加 IIS_IUSRS 用户
4. 权限：读取和执行、列出文件夹目录、读取

第五步：启动网站

1. 在IIS中选择网站
2. 右键 → 管理网站 → 启动
3. 测试访问：http://localhost:端口号

---

不同场景配置

场景1：基础Vue项目（最常用）

适用：简单的展示型网站，前后端分离，后端API已部署

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
  system.webServer>
configuration>

场景2：前后端同服务器部署

架构示例：

服务器（192.168.1.100）
├── IIS网站1 (端口80)   ← Vue前端
│   └── C:\inetpub\wwwroot\vue-app\
└── IIS网站2 (端口5000) ← .NET后端API
    └── C:\inetpub\wwwroot\api\

Vue项目API调用：

// 在Vue项目中直接调用后端API
axios.get('http://192.168.1.100:5000/api/users')

web.config：使用基础配置即可

场景3：前后端不同服务器 + API代理

架构示例：

前端服务器（192.168.1.100）    后端服务器（192.168.1.200）
├── IIS                        ├── IIS/Apache/Nginx
│   └── Vue项目                 │   └── API服务

优势：前端无需知道后端真实地址，避免跨域问题

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        
        <rule name="Proxy to API" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="http://192.168.1.200:5000/api/{R:1}" />
        rule>
        
        
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
  system.webServer>
configuration>

Vue项目API调用：

// 简化的API调用，会被自动代理
axios.get('/api/users')  // 实际访问：http://192.168.1.200:5000/api/users

场景4：子目录部署

部署路径：http://domain.com/myapp/

vue.config.js配置：

module.exports = {
  publicPath: '/myapp/'
}

web.config配置：

<rule name="Handle History Mode and hash fallback" stopProcessing="true">
  <match url="(.*)" />
  <conditions logicalGrouping="MatchAll">
    <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
    <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
  conditions>
  <action type="Rewrite" url="/myapp/" />  
rule>

场景5：企业级生产环境

特点：高安全性、高性能、多环境支持

<configuration>
  <system.webServer>
    
    <rewrite>
      <rules>
        
        <rule name="Redirect to HTTPS" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTPS}" pattern="off" ignoreCase="true" />
          conditions>
          <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" 
                  redirectType="Permanent" />
        rule>
        
        
        <rule name="API Proxy" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="https://api.company.com/{R:1}" />
        rule>
        
        
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
    
    
    <httpHeaders>
      <add name="X-Frame-Options" value="SAMEORIGIN" />
      <add name="X-Content-Type-Options" value="nosniff" />
      <add name="X-XSS-Protection" value="1; mode=block" />
      <add name="Strict-Transport-Security" value="max-age=31536000; includeSubDomains" />
      <add name="Referrer-Policy" value="strict-origin-when-cross-origin" />
      <add name="Content-Security-Policy" value="default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline';" />
    httpHeaders>
    
    
    <staticContent>
      <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="31536000" />
    staticContent>
    
    
    <urlCompression doStaticCompression="true" doDynamicCompression="true" />
    
    
    <httpErrors errorMode="Custom">
      <remove statusCode="404" subStatusCode="-1" />
      <error statusCode="404" path="/" responseMode="ExecuteURL" />
      <remove statusCode="500" subStatusCode="-1" />
      <error statusCode="500" path="/error.html" responseMode="ExecuteURL" />
    httpErrors>
  system.webServer>
configuration>

---

常见问题

问题1：HTTP 错误 500.19 - MIME类型冲突

错误信息：

在唯一密钥属性"fileExtension"设置为".js"时，无法添加类型为"mimeMap"的重复集合项

解决方案：

<staticContent>
  <remove fileExtension=".js" />
  <mimeMap fileExtension=".js" mimeType="application/javascript" />
staticContent>

问题2：页面刷新后404错误

原因：缺少URL重写规则

解决方案：确保web.config包含完整的重写规则

问题3：CSS/JS文件加载失败

原因：文件路径或权限问题

解决方案：

1. 检查文件是否完整复制
2. 确认IIS_IUSRS权限
3. 检查publicPath配置

问题4：API调用跨域错误

解决方案：

1. 在web.config中配置API代理
2. 在后端API中配置CORS
3. 使用nginx反向代理

问题5：子目录部署路径错误

解决方案：

1. 修改vue.config.js中的publicPath
2. 修改web.config中的重写目标
3. 确保路由配置正确

---

实用配置模板

模板1：开发/测试环境

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        
        <rule name="Dev API" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="http://localhost:3000/api/{R:1}" />
        rule>
        
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
    
    
    <httpHeaders>
      <add name="Access-Control-Allow-Origin" value="*" />
      <add name="Access-Control-Allow-Methods" value="GET, POST, PUT, DELETE, OPTIONS" />
      <add name="Access-Control-Allow-Headers" value="Content-Type, Authorization" />
    httpHeaders>
  system.webServer>
configuration>

模板2：生产环境（安全优化）

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        
        <rule name="Force HTTPS" stopProcessing="true">
          <match url="(.*)" />
          <conditions>
            <add input="{HTTPS}" pattern="off" />
          conditions>
          <action type="Redirect" url="https://{HTTP_HOST}/{R:1}" redirectType="Permanent" />
        rule>
        
        
        <rule name="Production API" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="https://api.production.com/{R:1}" />
        rule>
        
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
    
    
    <httpHeaders>
      <add name="X-Frame-Options" value="DENY" />
      <add name="X-Content-Type-Options" value="nosniff" />
      <add name="X-XSS-Protection" value="1; mode=block" />
      <add name="Strict-Transport-Security" value="max-age=31536000" />
    httpHeaders>
    
    
    <staticContent>
      <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="604800" />
    staticContent>
  system.webServer>
configuration>

模板3：多环境切换

<configuration>
  <system.webServer>
    <rewrite>
      <rules>
        
        <rule name="Dev API" enabled="false" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="http://localhost:3000/api/{R:1}" />
        rule>
        
        
        <rule name="Test API" enabled="false" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="https://test-api.company.com/{R:1}" />
        rule>
        
        
        <rule name="Prod API" enabled="true" stopProcessing="true">
          <match url="^api/(.*)" />
          <action type="Rewrite" url="https://api.company.com/{R:1}" />
        rule>
        
        <rule name="Handle History Mode and hash fallback" stopProcessing="true">
          <match url="(.*)" />
          <conditions logicalGrouping="MatchAll">
            <add input="{REQUEST_FILENAME}" matchType="IsFile" negate="true" />
            <add input="{REQUEST_FILENAME}" matchType="IsDirectory" negate="true" />
          conditions>
          <action type="Rewrite" url="/" />
        rule>
      rules>
    rewrite>
  system.webServer>
configuration>

---

部署检查清单

部署前检查

• Vue项目构建成功（npm run build）
• dist文件夹包含所有文件
• web.config文件已创建
• IIS已安装URL Rewrite模块

部署时检查

• 文件复制到正确位置
• IIS网站配置正确
• 应用程序池设置正确
• 文件权限设置正确

部署后检查

• 网站可以正常访问
• 路由跳转正常
• 页面刷新不出现404
• API调用正常
• 静态资源加载正常

---

性能优化建议

1. 启用压缩

<urlCompression doStaticCompression="true" doDynamicCompression="true" />

2. 设置缓存

<staticContent>
  <clientCache cacheControlMode="UseMaxAge" cacheControlMaxAge="2592000" />
staticContent>

3. 优化构建

// vue.config.js
module.exports = {
  productionSourceMap: false,  // 禁用source map
  configureWebpack: {
    optimization: {
      splitChunks: {
        chunks: 'all'
      }
    }
  }
}

---

总结

1. 理解SPA原理：Vue是单页应用，所有路由都要重定向到index.html
2. 核心配置不变：无论多少页面，基本的重写规则都一样
3. 按需添加功能：根据具体需求添加API代理、安全头等配置
4. 环境区分部署：开发、测试、生产使用不同的配置
5. 注意执行顺序：web.config规则从上到下执行，注意stopProcessing属性

通过本手册，您可以根据具体情况快速选择合适的配置模板，实现Vue项目在IIS上的成功部署！