企业官网建设流程全解析

做GIS前端开发的同行应该都很清楚，ArcGIS API for JavaScript是绕不开的一类东西。平时做原型和Demo，为了方便，基本都直接引用在线资源，一行script标签加载init.js，地图几分钟就能跑起来，完全不操心服务器、目录结构这些事。可一旦项目进入部署阶段，尤其是客户那边是隔离网络、内网环境，机器根本访问不到公网，那个在线地址就成了摆设。这时候就只能把整套JS API放到本地服务器上，让网页通过本地HTTP地址去加载，IIS自然是Windows服务器上最顺手的选择。

这篇文章不是官方文档的复读机，而是围绕ArcGIS API for JavaScript 4.13本地IIS服务器部署，整理了从方案选型、目录规划、IIS站点配置到常见故障排查的完整过程。适合正在做WebGIS开发、需要把在线API切到本地部署的开发者，也适合刚接到部署任务、对IIS不太熟的前端和项目实施人员。我会先把“为什么本地部署、为什么选4.13”讲清楚，再一步步拆解IIS站点怎么建、MIME和跨域怎么配，最后把最容易踩的坑逐个列出来，给你一份能直接照着操作的清单。

1. 为什么要在本地IIS上部署ArcGIS API for JavaScript

1.1 在线加载和本地部署怎么选

ArcGIS API for JavaScript官方默认推荐的是在线加载方式，开发阶段直接引用在线地址，省去维护安装包、处理依赖的麻烦，打开浏览器就能写代码。很多人开发了一两个月，直到部署时才发现问题：客户那台机器可能压根不在公网环境，或者因为网络策略限制，外网域名被限制访问、被限速、被DNS解析干扰，甚至某些浏览器安全策略禁止从http页面请求https资源。这时候必须把API本身变成项目部署包的一部分，放到客户自己的服务器上。

选择本地部署要注意的不只是“把js文件拷过去”，还包括底层加载机制、路径逻辑、服务器MIME类型、跨域请求规则、HTTPS混合内容等一整套东西。我见过不少同事第一次做本地部署时只拷了几个文件，页面死活加载不出来，就是因为没有把“在线加载时浏览器替我们处理的事情”完整地搬到本地服务器上。在线加载时，CDN域名和路径是固定的，init.js内部会根据自身地址去拼接模块路径，浏览器帮你处理了同源或跨域的许多流转；而本地部署后，这些细节全得你自己保证。

相比直接把页面和API全部放在本地IIS，也有一种做法是尝试把API打包进前端工程，通过构建工具把依赖打成chunk再发布。但ArcGIS API for JavaScript 4.13本身不是普通npm包，它的模块加载依赖一套完整的dojo运行时，很多构建方案兼容性并不好。对于大多数传统WebGIS项目，IIS静态站点就是最省事、最容易解释、也最容易排障的部署形态。测试时多花半小时把IIS配置整理干净，后面省下的是整条业务链路上的排查时间。

1.2 4.13版本有哪些需要留意的特点

4.13是4.x系列里比较成熟的一个版本，2D地图使用MapView，3D场景使用SceneView，底层依赖WebGL渲染。这个版本仍然使用AMD方式加载模块，也就是我们熟悉的require(["esri/Map"], ...)这种写法，而不是像后续部分版本那样开始支持新的ES Modules加载方式。这意味着你在4.13下写的代码，如果哪天要升级到4.20以上，除了API接口可能有变化，加载方式本身也要跟着调整，所以很多老项目干脆就把版本锁死在4.13。

从部署角度看，4.13有一个容易被忽略的点：它自带独立的dojo运行时、一套主题CSS、一堆图标字体和资源文件。也就是说，本地部署时我们不只要提供一个init.js，还要提供整个esri、dojo、themes等目录，否则地图模块、样式、控件图标都会出问题。很多项目组只拷贝了init.js和esri目录，最后页面能显示地图但丢图标、弹窗窗口变形，就是这个原因造成的。理解4.13的目录结构，是部署前必须做好的功课。

2. 部署前的准备：把安装包和IIS理顺

2.1 环境清单和安装包获取

部署前先把需要的组件列清楚。第一，一台安装了Windows Server或Windows 10/11的机器，上面开启了IIS。第二，ArcGIS API for JavaScript 4.13的安装包，也就是官方下载站那个压缩包。第三，一个规划好的物理目录，建议独立创建，方便以后升级、回滚和排查权限问题。

IIS开启方式不复杂，在控制面板的“启用或关闭Windows功能”里勾上Internet Information Services，并确保“常见HTTP功能”下的“静态内容”“默认文档”“目录浏览”“HTTP错误”这些子项被选中。很多人装了IIS但没勾“静态内容”，结果JS文件直接404或拒绝访问。这一步看着基础，实际排查时浪费的时间却不少，值得在部署前专门确认一次。

安装包最好去官方网站的开发者下载页找历史版本。有些项目组习惯从博客或网盘下压缩包，解压后发现版本不对甚至文件损坏，部署起来错误千奇百怪。我建议下载后立刻看一下压缩包大小，至少保证zip能完整解压，并且能看到arcgis_js_api、documentation这类顶层目录。另外，开发机器上用什么版本，部署机器就尽量用同一个版本，别开发时用4.13，部署包却是4.12，等地图组件调用新API时才发现版本不一致，到时候排查会非常痛苦。

2.2 解压后的目录结构说明

解压4.13的压缩包后，顶层目录一般是arcgis_js_api和documentation。部署只需要arcgis_js_api目录，里面主要的路径是library/4.13/，library目录下放着init.js、dojo、esri、themes等文件。library/4.13/init.js是我们最终要在页面里加载的入口文件，library/4.13/esri存放核心模块，library/4.13/dojo是API自带的运行时，library/4.13/themes里是浅色和深色主题的CSS文件。

所以IIS站点的物理路径最好设置为一个专门存放整个arcgis_js_api的目录，比如D:\WebSites\GISAPI\arcgis_js_api。在IIS里建立网站时，把站点主目录指到D:\WebSites\GISAPI就行。这样访问的时候用http://主机名/arcgis_js_api/library/4.13/init.js就能打开入口文件，逻辑和官方文档里本地部署的路径风格一致。不要把压缩包直接解压散落在桌面或临时文件夹，否则后面设置权限、快速定位文件都会很麻烦。

还有一个细节，除非特殊情况，不要在站点根目录下再挂一层虚拟目录指向arcgis_js_api，除非你完全清楚虚拟目录带来的URL路径映射变化。因为init.js内部还会相对当前地址去拼接模块路径，虚拟目录可能会让路径错一位，报出“Could not load module”这类问题。最省心的方法就是让URL路径和物理目录保持一致，不要额外制造一层映射关系。

3. 在IIS上搭建站点并完成配置

3.1 创建网站和物理目录的要点

打开IIS管理器，右键“网站”选择“添加网站”。网站名称随便起，比如“GISAPI”。物理路径选择之前准备好的目录。绑定类型选http，端口可以保持默认80，也可以单独指定8080或其它端口，取决于这台服务器上是否已有别的站点占用了80端口。主机名一般留空，直接用IP或机器名访问即可。

创建完站点后，IIS会自动生成一个默认应用程序池。对于纯静态站，建议把应用程序池的“.NET CLR版本”设置为“无托管代码”，托管管道模式保持集成模式。这不是必须的，但可以避免静态请求进入.NET管线后出现额外的重定向和错误。我有一次部署时，因为应用池默认是.NET v4.0，静态请求偶尔会多出一些奇怪的状态码，改成无托管代码后立刻清净了。

物理目录确定后，还要检查NTFS权限。IIS进程访问物理目录的账号默认是IIS_IUSRS或应用程序池身份，如果解压目录是从压缩包直接拷贝过来的，权限继承通常没问题。但如果某个上级目录设置过严格权限，就可能在浏览器里看到403错误。解决办法是右键物理目录，在“属性-安全-编辑”中添加IIS_IUSRS的读取权限。很多部署问题不是IIS配置错了，而是Windows文件系统权限把匿名访问挡在了外面。

3.2 配置MIME类型和静态文件支持

IIS对静态文件返回什么Content-Type，由MIME类型表决定。4.13本地部署时，init.js、main.css、字体文件、json配置都要能正确返回。较新的IIS版本默认已包含.js、.css、.png、.json等常用类型，不用额外加，但字体文件非常容易被漏掉。

如果页面加载后地图控件图标全部变成方框，或者控制台报字体文件404，基本就是woff/woff2的MIME缺失。操作方法是在IIS管理器中选中站点，双击“MIME类型”，查看列表里有没有.woff和.woff2。没有就添加：扩展名.woff，MIME类型application/font-woff；扩展名.woff2，MIME类型application/font-woff2。某些版本还需要.ttf和.svg，建议顺手一起补上，省得以后换主题时再踩一次。

另外，如果你访问站点根目录希望自动打开测试页面，还需要在“默认文档”里添加index.html。项目初期建议开启“目录浏览”，方便直接验证文件是否都在；正式上线时再关掉，避免暴露文件结构。静态站点的配置核心就是“让IIS老老实实把磁盘上的文件按原样返回”，所有和这目标无关的配置都可以简化。

3.3 跨域请求头与CORS处理

本地部署常见的一个误区是“我已经把API放在本地了，怎么页面里还有跨域报错”。先理清楚：只要页面本身也是从同一个IIS站点加载的，页面里引用的API、CSS、图片都属于同源请求，不会存在CORS报错。真正会触发跨域的，是以下几种场景：页面放在另一台服务器，API部署在这台IIS；页面请求部署在其他服务器上的地图服务、要素服务；开发阶段你直接双击本地HTML文件，用file://协议打开页面，再去请求http://localhost下的API。最后一种跨域非常典型，浏览器会直接拦下来，因为Origin为null的请求都被视为跨域。

如果你的部署模式真的需要让其他源访问，可以在IIS里给站点添加“HTTP响应头”，加一个Access-Control-Allow-Origin，值设为*。这样浏览器对静态资源的跨域请求基本能通过。但要提醒一句，*意味着任意来源都能读取，内网或受限网络环境没问题，公开站点就别这么干，最好明确指定允许的源。另外，如果地图服务是由ArcGIS Server发布的，服务端本身也有CORS配置，光在IIS里加响应头往往没有用，需要后端服务配合给出正确的跨域响应头。

3.4 页面里引用本地API的最小示例

部署完成后，建议先写一个最简单的测试页面验证。假设IIS站点绑定的是8080端口，页面放在同一站点的mapapp/index.html目录下。页面里引用API的方式如下：

<!DOCTYPE html> <html lang="zh-CN"> <head> <meta charset="utf-8"> <meta name="viewport" content="width=device-width, initial-scale=1"> <title>本地API测试页面</title> <link rel="stylesheet" href="http://localhost:8080/arcgis_js_api/library/4.13/esri/themes/light/main.css"> </head> <body> <div id="viewDiv" style="width:100%;height:100vh;"></div> <script src="http://localhost:8080/arcgis_js_api/library/4.13/init.js"></script> <script> require([ "esri/Map", "esri/views/MapView" ], function(Map, MapView) { var map = new Map({ basemap: "streets" }); var view = new MapView({ container: "viewDiv", map: map, zoom: 4, center: [116.39, 39.9] }); }); </script> </body> </html>

这里有两个地方特别容易写错：第一，CSS路径里不要漏掉themes/light/main.css，不加载样式的话地图容器会没有基本UI；第二，init.js放在body尾部、viewDiv之后，否则页面刚渲染时容器还不存在，MapView创建会失败。我习惯先写div，再在body末尾引脚本。另外，规划线上地址时，如果IIS能用80端口就尽量用80，省的每个引用URL都要带端口，后续批量替换很麻烦。

4. 部署后立刻会踩到的典型问题

4.1 init.js返回404或403

部署完打开页面，控制台第一个报错往往就是init.js返回404或403。404大部分原因是路径不对，比如页面引用了http://localhost/arcgis_js_api/library/4.13/init.js，但IIS站点的物理目录已经指向了D:\WebSites\GISAPI\arcgis_js_api，等于多套了一层arcgis_js_api。这时实际请求的物理路径是D:\WebSites\GISAPI\arcgis_js_api\arcgis_js_api\library\...。解决办法很简单：要么把站点物理目录指到包含arcgis_js_api的那一层，要么把引用路径里的arcgis_js_api去掉，让URL和物理目录严格对应。

403则常见于NTFS权限不足、IIS未开启静态内容、或者应用程序池身份无法访问目录。快速定位方法是先在服务器本机浏览器里直接访问init.js地址，如果在服务器本机都403，基本是权限或IIS配置问题；如果服务器本机能访问但局域网其他机器不能访问，就要检查Windows防火墙是否放行了绑定的端口。防火墙问题往往不在IIS本身，而是8080这类非默认端口没有放行，导致外部请求根本没到IIS。

4.2 控制台出现CORS跨域报错

报错类似Access to XMLHttpRequest at 'http://localhost:8080/arcgis_js_api/...' from origin 'null' has been blocked by CORS policy。出现origin 'null'，说明页面是用file://方式打开的，或者是从某些IDE内置预览里打开的。这种情况下无论怎么加CORS响应头都容易反复出问题，最干脆的办法是别拿本地文件直接点开测试，把测试页面放到IIS站点下，通过http://localhost:8080/mapapp/访问。同为http源，跨域自然消失。

另一种跨域是页面部署在A服务器，API部署在B服务器，通过http://b:8080/arcgis_js_api/...引用。如果B的IIS没有设置CORS响应头，浏览器就会拦截。按前面步骤在B站点添加Access-Control-Allow-Origin: *即可。如果页面是https，API也尽量是https，否则浏览器会因为混合内容阻止普通http请求，尤其是Chrome浏览器对mixed content非常严格。很多部署在https环境下的项目，就是被这个混合内容问题卡住，页面控制台却只提示“已被阻止”，很容易误判成API路径错。

4.3 字体图标或主题样式加载失败

页面能出地图，但缩放按钮、底图切换按钮上的图标变成小方框，或者弹窗里的箭头消失，多半是字体文件404。ArcGIS API的CSS里用了不少自定义图标字体，这些字体文件在esri/themes/base/icons/fonts目录下，扩展名主要是woff和woff2。刚才说的MIME类型没配好，浏览器根本不认这些文件，于是图标全丢。

排查时按F12打开网络面板，找到字体文件哪个返回404，再去IIS的MIME类型表对照扩展名。补上.woff、.woff2的MIME之后，强制刷新页面。有些浏览器对字体跨域也有要求，如果页面的源和API不同，需要按4.2的方式配CORS响应头。顺手把.ttf和.svg也加上，免得后续换主题或升级版本时，同样的坑再踩一遍。这个问题的特点是“地图能用但界面残缺”，经常被当成样式兼容问题排查很久。

4.4 页面不报错但地图一片空白

这是最让人头疼的一类问题，控制台不一定有红字，只能看到地图容器是空的。先检查浏览器是否支持WebGL，4.13的SceneView必须依赖WebGL，如果浏览器禁用了硬件加速、显卡驱动太老或远程桌面会话里没有正常初始化GPU，会出现绿色区域背景或者完全空白，MapView受WebGL影响小一些，但底层渲染也可能异常。还有一个非常常见的坑是底图网络请求失败，比如页面里配置的底图是官方在线底图streets、topo-vector，但部署环境是纯内网，请求发不出去，数据层就拉不到瓦片，视觉上地图是空白或灰块。解决办法是改用本地发布的地图服务，或指定离线缓存底图地址。

还有一种“地图空白+控制台有Could not load module”的错误，是模块路径没对上。比如从别的项目复制页面，但API实际部署在别的端口或子路径，引用时路径写错了，require里的esri/Map自然加载不出来。此时检查页面里init.js的URL与实际访问是否一致，再直接浏览器打开http://xxx/arcgis_js_api/library/4.13/esri下某个具体模块js文件，确认能否返回200。只要模块文件能打开，说明路径没写错，问题多半在业务代码或底图请求。

5. 我的一些部署经验和检查清单

5.1 部署前先帮自己省掉一半排查时间

强烈建议在第一次部署时，先做一个“裸环境验证”，还没写任何业务代码之前，建一个最简单的静态页面，只引入main.css和init.js，再画一个最基础的MapView。这个页面能正常出来，说明API的IIS部署已经通了；如果这步都不通，后面加再多业务代码也都是在这上面叠错误。很多同事一上来就部署整个项目，结果几十个请求全部失败，分不清是代码问题、API路径问题还是服务器问题。

第二个省时间的建议，是把测试页和API放在同一个站点里。页面源和API同源，可以绕开大量CORS问题。尤其在内网有多个应用需要访问API时，不要急着分散部署，先集中放一个站点上跑通。如果实在要跨站访问，再把CORS响应头、跨域策略这些事情单独拎出来验证。记住一个原则：每次只引入一个变量，页面从同一个站点加载API，先把“同源”这个前提守住，排查难度会低很多。

5.2 常用排查命令和工具

排查IIS部署，浏览器F12的网络面板最常用，按状态排序，404和500会一眼看出来。如果某个静态资源404，直接把完整URL复制到浏览器地址栏重新访问，看IIS返回什么错误码。403.14一般是目录浏览被禁用而且没有默认文档，404.3多半是MIME类型缺失，401则是权限问题。在服务器本机还可以用命令行curl -I http://localhost:8080/arcgis_js_api/library/4.13/init.js看响应头，快速判断文件是否可用。

如果碰到“服务器本机能访问、别的机器不能访问”，先检查Windows防火墙是否放行了对应端口。IIS站点绑定的是8080，防火墙默认可能只允许80或445，需要到“高级安全Windows防火墙”里添加入站规则放行TCP 8080。这一步很多人忽略，最后发现不是IIS问题，而是网络层直接把流量挡了。还有一个小技巧，用别的机器访问时，尽量用浏览器无痕窗口，避免浏览器缓存把旧版本JS带出来，造成“改了没生效”的错觉。

5.3 后续升级版本和复用部署包时留个心眼

老项目锁定4.13没什么问题，但以后如果客户要求升级到新版本，不要直接在原目录上覆盖解压，最好把新版本放到同级目录，比如D:\WebSites\GISAPI\arcgis_js_api_420，然后修改页面引用路径，测试通过后再切换默认路径。覆盖式升级会让浏览器缓存里的旧JS和CSS混杂在一起，问题非常难查。我吃过这个亏，最后只能逐个清缓存，后来就养成了保留多版本目录的习惯。

另外，如果多个项目都要用本地API，不建议每个项目都复制一份几十MB的arcgis_js_api目录，可以在IIS里建一个公共API站点，其他站点通过固定地址引用。不过这样就不是同源了，需要在公共API站点上配好CORS，业务页面才能跨域加载。或者更简单，把arcgis_js_api作为虚拟目录挂在多个业务站点下，URL路径保持一致，也能避免复制多份文件，但要注意虚拟目录的物理路径权限和应用程序池身份。

最后再分享一个我沿用至今的做法：部署完成后，新建一个只有首页和一行代码的简单测试页，每次排查问题时优先用这个页面做对照，因为它足够简单，能最快判断当前问题到底出在IIS层、API层还是业务代码层。这个习惯看着不起眼，但在多次项目交付、半夜上线前救过场。部署本地ArcGIS API这事不难，难的是把每个环节都拆得足够清楚，清楚到出错时能迅速定位到具体配置项，而不是在整个IIS和代码里漫无目的地翻。