网站建设并不是一条直线。

这次实践中，真正耗费时间的往往不是“写代码”，而是判断问题发生在哪里：操作错误、环境配置、内容结构、浏览器兼容，还是部署缓存。

下面按问题类型整理主要故障及经验。

一、PowerShell阻止运行npm脚本

现象

安装Node.js后，执行：

npm -v

或：

npm run dev

PowerShell提示脚本被系统策略禁止运行。

原因

Windows的PowerShell执行策略限制了本地脚本运行。npm本身已经安装，但对应的PowerShell脚本无法执行。

处理方法

执行：

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

确认后关闭终端，再重新打开。

也可以临时使用：

npm.cmd run build

经验

看到命令失败时，不要立刻重装Node.js。先判断是软件没有安装，还是终端执行策略阻止了它。

二、命令输入错误

现象

曾把：

npm

误输入为：

nmp

终端提示找不到命令。

原因

单纯的拼写错误。

处理方法

重新核对命令后执行。

经验

终端报错不一定代表环境复杂故障。先检查：

  • 命令拼写；
  • 当前目录；
  • 文件名；
  • 路径；
  • 中英文符号。

最简单的错误，往往最容易被过度分析。

三、VS Code处于受限模式

现象

VS Code打开项目后，部分扩展、终端或代码功能不能正常运行。

原因

VS Code没有信任当前工作区，自动进入Restricted Mode。

处理方法

确认项目来源可信后，选择信任该工作区。

经验

新电脑第一次打开本地项目时，应先检查工作区信任状态。否则容易把权限问题误判为扩展或项目问题。

四、把Copilot和Codex混为一谈

现象

早期容易把VS Code中的代码补全工具、聊天工具和Codex项目执行能力混在一起。

原因

它们都与代码和AI有关，但角色不同。

处理方法

本项目最终形成清晰分工：

  • GPT负责规划、拆解和审查；
  • Codex负责读取项目、修改文件、运行构建；
  • VS Code负责编辑和终端操作；
  • Git负责版本管理。

经验

使用AI工具前，先明确每个工具能做什么、不能做什么。工具越多，越需要清楚分工。

五、文件没有保存，Codex读取到旧内容

现象

用户已经在VS Code中修改文档，但Codex读取时仍发现文件为空或内容没有变化。

原因

修改只存在于编辑器中，还没有保存到磁盘。

处理方法

执行Codex任务前先保存全部文件：

Ctrl + Shift + S

或使用VS Code的“全部保存”。

经验

AI读取的是磁盘文件，不是编辑器里尚未保存的画面。让AI处理本地项目之前，必须先确认文件已经保存。

六、Git无法提交：用户身份未配置

现象

第一次执行：

git commit

Git提示不知道提交者姓名和邮箱。

原因

新电脑上的Git没有配置用户身份。

处理方法

执行：

git config --global user.name "你的名字"
git config --global user.email "你的邮箱"

检查：

git config --global --list

经验

Git提交不仅保存代码，还记录是谁完成了提交。新设备首次使用Git时，应提前配置身份。

七、空目录没有进入Git

现象

本地已经创建某个目录，但推送到GitHub后看不到。

原因

Git只跟踪文件，不跟踪空目录。

处理方法

在目录中加入实际文件，或暂时放置.gitkeep。

经验

“本地存在”不等于“Git已经记录”。应通过：

git status

确认哪些文件真正进入版本管理。

八、LF与CRLF提示

现象

Git提示某些文件以后可能从CRLF转换为LF，或反向转换。

原因

Windows常用CRLF，Linux和多数Web项目常用LF。Git会根据配置进行行尾转换。

处理方法

只要：

git diff --check

通过，而且构建正常，通常不需要紧张。

必要时可以通过.gitattributes统一规则。

经验

行尾提示不等于文件损坏。真正需要检查的是：

  • 是否产生无意义的大量差异；
  • 构建是否正常；
  • 格式检查是否通过。

九、示例内容与正式内容混杂

现象

网站早期为了验证内容系统，建立了简短示例文章。正式上线前，这些文章仍可能出现在列表和sitemap中。

原因

技术验证内容使用了：

draft: false

系统会把它当作正式文章。

处理方法

完整文章没有完成前，设置为：

draft: true

正式内容定稿后再改回：

draft: false

经验

“能显示的页面”不等于“应该发布的内容”。技术状态和编辑状态必须分开管理。

十、聊天内容直接迁入网站后过长

现象

第一、二节内容从对话中迁入后，篇幅过长，概念重复，网页阅读负担较大。

原因

聊天适合逐步解释和反复确认；正式文章需要更紧凑的结构。

处理方法

重新整理文章：

  • 删除重复解释；
  • 合并相近章节；
  • 每节集中解决一个问题；
  • 保留关键概念、类比和结论；
  • 控制网页阅读长度。

经验

AI对话是素材，不是成稿。内容发布前必须经历重新编辑。

十一、课程排序规则不明确

现象

导读、正式课程和章末总结放在同一集合后，排序和统计容易混乱。

原因

只靠文件名或标题无法稳定表达课程角色。

处理方法

建立统一规则：

lesson: 0    导读
lesson: 1–98 正式课程
lesson: 99   章末总结

统计正式课程时，只计算1至98。

经验

内容网站不能只依靠人工记忆。凡是需要长期扩展的内容，都应建立机器可以识别的规则。

十二、标题在列表页重复

现象

课程列表中同时出现：

章末总结
第一章总结：建立AI基础认知框架

视觉上重复。

原因

左侧已经标明内容类型，右侧又完整显示文章正式标题。

处理方法

只在列表展示层删除“第N章总结：”前缀，文章正式标题保持不变。

经验

内容数据与页面展示不应强行共用一种格式。正式标题可以完整，列表标题可以适度简化。

十三、短页面页脚没有贴近底部

现象

内容较少的列表页中，页脚下面仍有大片空白。

原因

页面没有建立完整的纵向弹性布局。

处理方法

让页面主体使用：

body {
  min-height: 100vh;
  display: flex;
  flex-direction: column;
}

main {
  flex: 1;
}

经验

不要针对某一个短页面单独补丁。能在全站布局层解决的问题，应统一解决。

十四、误入Cloudflare Workers部署流程

现象

连接GitHub后，Cloudflare页面要求填写：

npx wrangler deploy

原因

进入了Workers部署入口，而不是Pages。

处理方法

返回创建页面，选择：

Pages
→ Import an existing Git repository

Astro静态网站的配置应包括：

Build command: npm run build
Build output directory: dist

经验

平台名称相近，不代表流程相同。看到与项目类型不符的字段时，应停下来判断是否进入了错误入口。

十五、正式域名未确定，canonical不能乱写

现象

网站需要生成canonical、robots和sitemap，但正式域名尚未确定。

原因

这些文件都需要绝对网址。

处理方法

使用环境变量：

SITE_URL

本地构建使用明确无效的回退地址：

https://example.invalid/

部署时配置真实的pages.dev地址。

经验

不要为了“先让构建通过”而伪造正式域名。所有依赖站点地址的功能，应共享同一个配置来源。

十六、390px模拟通过，真实折叠手机异常

现象

网站在电脑和390px模拟窗口中显示正常，但在真实折叠手机上出现多栏被压缩的问题。

原因

真实设备上报的CSS视口不一定等于物理分辨率，也不一定落在常见手机宽度范围。

折叠状态和展开状态的视口差异很大。

处理方法

建立临时视口诊断页，采集：

  • window.innerWidth
  • window.innerHeight
  • clientWidth
  • screen.width
  • devicePixelRatio
  • visualViewport
  • 媒体查询命中结果

经验

响应式设计不能只依赖模拟器。关键设备必须实机测试。

十七、只按宽度划分布局不够

现象

iPhone横屏宽度达到852px，折叠手机展开宽度约700px。若只按宽度切换双栏，iPhone横屏也会进入平板布局。

原因

iPhone横屏虽然较宽，但高度只有约349px；折叠手机展开后高度约750px，两者使用场景不同。

处理方法

最终同时使用宽度和高度：

默认：手机单栏

宽度≥680px
且高度≥600px
且宽度<1050px：
平板双栏

宽度≥1050px
且高度≥500px：
桌面布局

经验

布局判断的本质不是设备名称，而是内容可用空间。

十八、旧版Chrome无法运行诊断脚本

现象

Firefox可以显示诊断数据，Chrome中页面框架正常，但所有数据一直显示“—”。

原因

手机上的Chrome内核只有74版本。诊断脚本被构建为现代ES模块，包含可选链、空值合并等语法，旧内核可能在解析阶段直接失败。

处理方法

临时把诊断工具改为兼容性更高的经典脚本，并增加：

  • 脚本运行状态；
  • 基础探针；
  • 逐项安全读取；
  • 页面可见错误信息；
  • 复制诊断数据功能。

经验

页面HTML能显示，不代表JavaScript已经运行。兼容性问题可能发生在脚本解析阶段，普通try/catch无法捕获。

十九、折叠手机Chrome不能自动切换布局

现象

折叠手机上的旧版Chrome，无论屏幕折叠还是展开，都保持单栏；Firefox可以正常切换。

原因

旧版Chrome对折叠屏动态视口更新支持较弱。

处理方法

将Chrome从74升级到151。升级后，折叠状态自动使用单栏，展开状态自动切换双栏。

经验

出现设备适配异常时，要同时检查：

  • 网站CSS；
  • 浏览器版本；
  • 系统缩放；
  • 缓存；
  • 视口是否真正更新。

不要把所有问题都归因于代码。

二十、删除页面后仍然可以访问

现象

临时诊断页已经从代码中删除，最新部署也成功，但原地址仍返回旧页面。

原因

Cloudflare边缘节点缓存了旧页面：

CF-Cache-Status: HIT
Cache-Control: public, s-maxage=604800

缓存有效期达到7天。

处理方法

通过：

curl.exe -I 页面地址

检查服务器返回状态。

带随机查询参数的地址已经返回404，说明最新部署正确；旧无参数URL只是等待边缘缓存过期。

经验

浏览器显示旧页面时，不能只凭肉眼判断缓存位置。应检查响应头，区分：

  • 浏览器缓存；
  • Cloudflare边缘缓存；
  • 构建缓存；
  • 旧部署地址；
  • 当前生产部署。

二十一、不要为了旧浏览器污染正式架构

现象

面对Chrome 74异常，可以考虑增加专用CSS或JavaScript强制重排。

判断

这种处理会让正式代码承担长期维护成本，而问题已经可以通过升级浏览器解决。

处理原则

网站保持：

  • 标准CSS媒体查询；
  • 不识别设备型号；
  • 不识别浏览器；
  • 不使用User-Agent切换布局；
  • 不为单一旧浏览器增加正式逻辑。

经验

兼容性不是越多越好。应先确定正式支持范围，再决定是否值得增加复杂度。

二十二、AI任务描述不清会造成返工

现象

当任务只写“美化网站”或“优化手机效果”时，AI可能扩大修改范围，或者解决了局部问题，却引入新的不一致。

处理方法

交给Codex的任务尽量明确：

  • 背景；
  • 目标；
  • 允许修改的文件；
  • 禁止事项；
  • 验收尺寸；
  • 构建命令；
  • 报告格式；
  • 是否允许提交。

经验

AI执行质量很大程度上取决于任务定义质量。清楚的边界，比一句“帮我做好”更有效。

二十三、不要让Codex自动提交

现象

如果Codex修改完成后直接提交，人可能还没有查看页面和差异。

处理方法

固定流程：

Codex修改
→ 构建检查
→ 报告
→ 人工审查
→ 决定是否提交

大多数Codex任务都明确要求：

不要执行Git提交

经验

AI可以完成修改，但版本节点应由项目负责人确认。

二十四、每次提交只包含一个稳定阶段

现象

如果内容、样式、部署和调试混在同一次提交中，出现问题后很难回溯。

处理方法

本项目按阶段提交，例如：

  • 建立网站骨架；
  • 建立Markdown内容系统；
  • 导入课程；
  • 优化阅读体验；
  • 完成视觉改版；
  • 增加上线基础能力；
  • 修复响应式布局；
  • 完成最终断点规则。

经验

小步提交不是形式主义，而是AI协作项目中的安全机制。

二十五、最终形成的检查顺序

遇到问题时，建议按下面顺序排查：

先确认现象
→ 检查输入和当前路径
→ 检查Git状态
→ 检查构建结果
→ 检查浏览器控制台
→ 检查真实视口
→ 检查网络响应头
→ 区分代码、设备、浏览器与缓存
→ 再决定是否修改代码

不要看到异常就立即让AI重写页面。

结语

这次实践中，最重要的经验不是某一条命令，而是建立了一套问题处理方式：

先用证据确定问题在哪一层，再选择成本最低、影响最小的解决方法。

AI可以快速提出方案、修改代码和运行检查，但人仍然需要负责三件事：

  • 判断问题是否真的被解决；
  • 判断解决方法是否值得长期保留；
  • 判断什么时候应该停止继续优化。

这也是AI参与真实工程项目时，人与AI最合理的分工。

相关内容