PORTABILITY TEST
该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。
> 该 DOCX 包含不完整的 Office 元数据关系，已使用兼容模式恢复正文和媒体。
可移植性、解耦与隐藏依赖测试规范
文件建议名称：PORTABILITY_TEST.md
1. 测试目的
本测试用于检查当前项目是否存在：
平台强绑定
域名强绑定
服务器强绑定
云服务强绑定
数据库强绑定
存储服务强绑定
API 强绑定
文件路径强绑定
本地开发环境依赖
第三方 CDN 强依赖
外部字体强依赖
特定操作系统依赖
特定端口依赖
特定目录依赖
隐藏环境变量依赖
隐藏全局工具依赖
不必要的第三方 SDK
难以替换的基础设施依赖
跨模块过度耦合
配置散落
硬编码
部署不可复现
换环境后无法运行的问题
本测试的目标不是判断：
当前电脑上是否可以运行。
而是判断：
当前项目能否在未知服务器、未知域名、未知部署平台、未知存储供应商、未知数据库环境下，以较低成本完成迁移和部署。
2. 核心原则
测试期间必须遵守以下原则。
2.1 先测试，后修复
第一轮测试期间：
禁止发现问题后立即修改代码。
必须先完整记录所有问题。
测试完成后统一输出：
问题位置
问题类型
严重程度
触发条件
影响范围
修复建议
未经明确要求，不得开始修复。
2.2 不允许只做静态判断
禁止仅通过阅读代码后得出：
未发现明显问题。
必须尽可能通过：
搜索
构建
启动
环境变化
配置变化
路径变化
网络变化
Provider 替换
干净环境
实际验证。
2.3 不允许为了通过测试修改测试条件
禁止：
修改测试要求
降低测试标准
注释问题代码
临时删除失败模块
为测试添加特殊绕过逻辑
把生产代码改成只适用于测试的代码
遇到失败后直接跳过
任何失败必须记录。
3. 第一阶段：静态扫描
首先对整个项目进行静态扫描。
重点扫描以下内容。
4. 域名硬编码扫描
搜索项目中所有：
http://https://www.
检查是否存在：
固定生产域名
固定 API 地址
固定 CDN 地址
固定图片地址
固定后台地址
固定跳转地址
固定 Webhook 地址
固定 OAuth 回调地址
允许存在的位置：
README
测试数据
示例文件
.env.example
明确标记的配置文件
业务代码中不得直接依赖具体域名。
发现后记录：
文件：行号：具体值：用途：是否可配置：风险：
5. IP 地址扫描
扫描 IPv4 / IPv6 地址。
重点检查：
192.0.2.10192.0.2.10192.168.*10.*172.*公网 IP
判断是否进入：
API 请求
数据库连接
上传逻辑
WebSocket
服务调用
回调地址
前端页面逻辑
生产逻辑不得依赖固定 IP。
6. 端口扫描
检查是否硬编码：
3000300151734173808080007860543233066379
以及其他服务端口。
判断端口是否：
可配置
只属于开发环境
泄漏到了业务逻辑
被前端直接依赖
7. 绝对路径扫描
搜索类似：
C:\D:\E:/Users//home//var//opt//root/
生产代码不得依赖开发者电脑绝对路径。
重点检查：
文件上传
图片资源
字体
日志
缓存
临时文件
数据库文件
构建脚本
部署脚本
8. 第三方平台扫描
搜索项目中所有特定平台名称。
包括但不限于：
VercelCloudflareNetlifyAWSAzureGoogle CloudFirebaseSupabaseHuawei CloudAliyunTencent CloudRailwayRenderFly.io
检查这些依赖是否：
A. 只存在于适配层
可以接受。
B. 大量散落于业务代码
视为架构问题。
9. 第三方 SDK 扫描
检查：
package.jsonlock 文件源码 import配置文件
列出所有第三方 SDK。
分类：
UI
数据库
存储
认证
日志
分析
部署
CDN
AI
邮件
搜索
图片处理
每项回答：
是否必须？是否可以替换？是否直接侵入业务代码？删除后影响范围多大？
10. 外部资源扫描
检查是否依赖：
Google Fonts
CDN CSS
CDN JS
外链字体
外链图标
外链图片
第三方脚本
在线组件库
在线追踪脚本
重点搜索：
@import url(<link<script src=fetch(axios(
必须明确哪些资源在断网后会失效。
11. 环境变量审计
列出项目当前使用的全部环境变量。
输出表格：
| 变量 | 用途 | 必填 | 默认值 | 缺失后表现 |
|---|---|---|---|---|
重点检查：
是否存在类似：
process.env.API_URL || “https://production.example.com”
这种情况视为风险。
原则：
关键基础设施变量缺失时，应明确报错，而不是偷偷回退到某个固定生产环境。
12. 配置散落检查
检查以下内容是否散落在多个页面和模块：
URL
API 地址
字体
颜色
路径
端口
上传限制
文件大小限制
分页数量
缓存时间
Provider 名称
数据库配置
存储 Bucket
Feature Flag
如果同一配置出现多个地方：
记录为：
Configuration Duplication
13. 业务层与基础设施层耦合检查
重点检查业务代码是否直接调用：
数据库 SDK云存储 SDK第三方认证 SDK部署平台 SDK云厂商 SDK
理想结构：
业务逻辑↓Service↓Interface↓Adapter↓具体 Provider
而不是：
页面↓某云厂商 SDK
14. 第二阶段：运行测试
完成静态扫描后开始实际测试。
第一轮禁止修复代码。
15. Clean Install Test
创建一个干净环境。
删除或不使用：
node_modules构建缓存.nextdistbuild缓存目录旧日志本地数据库缓存
只保留：
源代码package.jsonlock 文件配置模板必要文档
执行正常安装。
验证：
InstallBuildStart
记录：
PASS / FAIL
如果失败，记录完整原因。
16. Clean Build Test
禁止依赖之前生成的：
缓存
构建结果
临时文件
本地生成文件
执行全新 Build。
必须验证：
生产构建是否成功
17. Directory Relocation Test
将整个项目复制到完全不同目录。
例如原目录：
/project/starmo
测试目录：
/tmp/random-project-38291
Windows 可使用不同盘符和目录。
重新执行：
installbuildstart
目的：
发现隐藏绝对路径和工作目录假设。
18. Port Mutation Test
将开发或运行端口修改为其他端口。
至少测试：
41738088
验证：
页面
API
资源
登录
WebSocket
回调
上传
是否仍正常。
19. Domain Mutation Test
将网站域名模拟修改。
例如：
https://通用数字产品.com
替换为：
https://example.test
验证：
页面跳转
图片地址
SEO
Metadata
Canonical URL
API
登录
分享
下载
回调
是否存在域名依赖。
20. Host Mutation Test
测试：
localhost192.0.2.10192.0.2.10测试域名局域网 IP
检查服务是否假设固定 Host。
21. Base Path Test
模拟网站不是部署在：
/
而是：
/starmo/
重点检查：
图片字体CSSJS页面跳转API静态文件下载文件
发现是否存在固定根路径依赖。
22. Offline Runtime Test
断开外部互联网连接。
再启动项目。
检查：
核心页面能否加载
本地字体能否显示
UI 是否完整
图标是否丢失
CSS 是否缺失
JavaScript 是否失败
图片是否异常
是否存在第三方资源导致页面白屏
第三方业务功能本身允许失败。
但失败不得导致无关功能整体崩溃。
23. External Resource Failure Test
模拟以下资源不可访问：
外部字体CDN统计平台第三方 API外链图片第三方脚本
验证网站是否能够：
Graceful Degradation
即：
局部功能失败，
但整体网站仍然可使用。
24. Missing Environment Variable Test
逐项移除重要环境变量。
例如：
DATABASE_URLAPI_BASE_URLSTORAGE_KEYSTORAGE_ENDPOINTSITE_URL
验证系统是否：
正确：
启动时明确告诉用户缺少哪个变量。
错误：
运行到某个页面才莫名报错。
严重错误：
偷偷 fallback 到生产服务器。
25. Invalid Configuration Test
故意提供错误值：
错误数据库地址错误存储 Endpoint无效 Token错误路径错误端口
检查：
报错是否明确
是否泄露敏感信息
是否导致整个系统崩溃
是否影响无关模块
26. Provider Removal Test
临时关闭一个外部 Provider。
例如：
Storage ProviderDatabase ProviderAnalytics ProviderEmail ProviderAI Provider
测试：
Provider 不可用时，
是否只影响对应模块。
不应：
上传服务失败↓整个后台失败↓整个网站失败
27. Provider Swap Test
如果项目使用 Adapter / Interface 架构，
创建一个最简单的测试 Provider。
例如：
FakeStorageAdapter
实现最基础：
uploadreaddelete
将真实 Provider 替换。
如果大量业务文件必须同时修改：
说明 Provider 并未真正解耦。
记录需要修改：
文件数量代码范围模块范围
28. Database Coupling Test
分析当前数据库依赖。
检查切换数据库时需要修改多少内容。
业务层不应该大量存在：
Supabase 特定写法Firebase 特定写法Prisma 特定结构SQL 方言云厂商专属 API
允许在：
RepositoryAdapterInfrastructure
层存在。
29. Storage Coupling Test
模拟当前存储服务退出。
回答：
如果明天更换：
Cloudflare R2→Huawei OBS
需要修改多少文件？
输出：
预计修改文件数量：业务层修改：Infrastructure 修改：UI 修改：配置修改：
如果必须大面积修改业务页面：
判定存在强耦合。
30. Linux Compatibility Test
如果开发环境为 Windows，
必须在 Linux 环境执行：
installbuildtest
重点检查：
路径分隔符
文件名大小写
Shell 命令
权限
环境变量
文件系统差异
31. Case Sensitivity Test
检查：
Logo.pnglogo.pngLOGO.png
等问题。
Windows 可能正常。
Linux 可能失败。
必须扫描所有 import 和静态资源引用。
32. Fresh Environment Test
在一个没有以下内容的环境执行：
全局 npm 包IDE 插件开发者环境变量开发者 SSH 配置开发者 Git 配置依赖特殊系统 PATH本地数据库本地缓存
只按照项目文档操作。
验证是否可以运行。
33. Dependency Reproducibility Test
验证是否存在：
开发者本地安装了某包但 package.json 没有记录
或：
依赖版本不明确
必须检查：
package.jsonlock 文件Node 版本Package Manager 版本
34. Secret Scan
扫描：
API Key
Token
Password
Secret
Access Key
Private Key
Cookie
Session
数据库密码
重点搜索：
sk-tokensecretpasswordapikeyapi_keyaccess_keyprivate_key
发现后立即标记：
CRITICAL
第一阶段只报告，不擅自删除或更换。
35. Git / Repository Leak Test
检查敏感文件是否可能进入 Git。
确认：
.env.env.local密钥私钥日志数据库文件上传文件缓存构建产物
是否正确忽略。
36. 第三阶段：隐藏假设测试
完成已知测试后，
不得直接结束。
需要主动寻找：
当前测试规范没有明确列出，但未来迁移时可能产生问题的隐藏假设。
至少检查：
时间区
Locale
编码
文件权限
文件系统
CPU 架构
Node 版本
浏览器差异
HTTPS 假设
Cookie Domain
CORS
CSP
Proxy
Reverse Proxy
WebSocket
CDN
Cache
Session Storage
Upload Path
MIME Type
文件名编码
中文路径
数据库时区
日期格式
大小写敏感
环境变量格式
Runtime 差异
发现任何项目特有的问题必须追加。
37. 架构影响范围测试
选择以下任意一个变更进行分析：
更换数据库更换云存储更换域名更换服务器更换部署平台更换字体更换 CDN
回答：
需要修改多少个文件？
理想状态：
配置+Adapter+极少量基础设施代码
而不是：
大量页面大量组件业务代码APIUI
38. 禁止项
项目正式业务代码中尽量不得存在以下形式：
固定域名固定公网 IP固定端口固定本地路径生产密钥生产 Token云厂商专属逻辑散落数据库 SDK 散落外链核心字体外链核心 UI 资源未经说明的第三方脚本隐藏 fallback
39. 测试评分
最终输出 0–100 分。
Domain Independence
__/100
Server Independence
__/100
Platform Independence
__/100
Storage Independence
__/100
Database Independence
__/100
API Independence
__/100
Resource Independence
__/100
Configuration Quality
__/100
Build Reproducibility
__/100
Environment Independence
__/100
Maintainability
__/100
40. 总评分
输出：
通用数字产品 Portability Score:__/100
并给出等级：
95–100 Excellent85–94 Good70–84 Needs Improvement50–69 High Coupling Risk0–49 Not Portable
41. 问题严重等级
所有问题必须分类。
P0 — Critical
例如：
Secret 泄露
必须使用特定服务器
无法 Clean Build
大范围平台锁定
生产配置硬编码
P1 — High
例如：
更换存储需要修改大量业务代码
域名大量硬编码
本地路径依赖
平台 SDK 深度侵入业务层
P2 — Medium
例如：
配置重复
部分资源依赖 CDN
错误处理耦合
Base Path 不兼容
P3 — Low
例如：
文档缺失
配置命名不统一
非关键资源可移植性较弱
42. 最终测试报告格式
必须严格输出：
# XXXXXXX Portability Audit Report## 总结Overall Score:主要风险：是否建议上线：—## P0### Issue 001文件：位置：问题：测试方式：测试结果：影响：建议：—## P1…—## P2…—## P3…—# Portability ScoreDomain Independence:Server Independence:Platform Independence:Storage Independence:Database Independence:API Independence:Resource Independence:Configuration Quality:Build Reproducibility:Environment Independence:Maintainability:Overall:—# Hidden Assumptions列出本次测试中新发现、原测试规范没有明确指出的问题。—# Migration Simulation如果明天迁移至：- 新服务器- 新域名- 新对象存储- 新数据库- 新部署平台分别需要修改：文件：配置：代码：基础设施：预计风险：—# ConclusionPASS / CONDITIONAL PASS / FAIL
43. 第一轮执行要求
当前阶段只执行：
检测测试记录分析输出报告
禁止：
修复重构升级依赖删除依赖更换架构自动修改配置
除非我后续明确要求：
开始修复。
44. 测试顺序
严格按照：
静态扫描↓依赖审计↓配置审计↓Clean Install↓Clean Build↓目录迁移↓端口变化↓域名变化↓Base Path↓断网↓外部服务故障↓环境变量缺失↓Provider Removal↓Provider Swap↓Linux Compatibility↓Secret Scan↓隐藏假设分析↓迁移模拟↓最终报告
45. 最终原则
本测试的目标不是证明项目：
在当前环境能够运行。
而是证明：
即使域名、服务器、部署平台、数据库、存储服务、目录、端口和运行环境全部改变，项目仍然具有清晰、可控、低成本的迁移路径。