章
目
录
React项目引入Service Worker可以带来诸如离线访问、性能优化等诸多好处。要是再结合TypeScript，不仅能提升代码的可读性和可维护性，还能利用TypeScript的类型检查功能减少错误。下面就详细讲讲在React项目中使用TypeScript编写Service Worker的具体方法。
一、前期准备
要在React项目里使用TypeScript编写Service Worker，首先得确保项目支持TypeScript。可以通过create-react-app工具来创建支持TypeScript的React项目，执行下面的命令：
npx create-react-app my-app --template typescript
cd my-app
npm install @types/service_worker_api --save-dev
上述命令中，npx create-react-app my-app --template typescript用于创建一个名为my-app的React项目，并使用TypeScript模板；cd my-app进入项目目录；npm install @types/service_worker_api --save-dev则是安装service_worker_api的类型定义文件，方便在TypeScript中使用相关API。
二、创建Service Worker文件
在项目的src目录下新建sw.ts文件，这就是我们编写Service Worker代码的地方。
// src/sw.ts
// 定义一个自定义事件类型，用于更新允许的域名列表
interface DomainUpdateEvent extends ExtendableEvent {
detail: {
domains: string[];
};
}
// 定义允许请求的域名列表
const ALLOWED_DOMAINS: string[] = ['api.example.com'];
// 监听fetch事件，处理网络请求
self.addEventListener('fetch', (event) => {
// 获取请求的URL
const requestURL = new URL(event.request.url);
// 获取请求的域名
const requestedDomain = requestURL.hostname;
// 判断请求的域名是否在允许列表中
if (ALLOWED_DOMAINS.includes(requestedDomain)) {
console.log(`[SW] 允许请求: ${event.request.url}`);
// 示例：添加请求头
const modifiedHeaders = new Headers(event.request.headers);
modifiedHeaders.append('X-SW-Optimized', 'true');
// 用修改后的请求头发起请求，并返回响应
event.respondWith(
fetch(event.request, {
headers: modifiedHeaders
})
);
}
});
// 监听message事件，用于动态更新允许的域名列表
self.addEventListener('message', (e: DomainUpdateEvent) => {
if (e.detail?.domains) {
// 将新的域名添加到允许列表中
ALLOWED_DOMAINS.push(...e.detail.domains);
console.log('[SW] 更新白名单:', ALLOWED_DOMAINS);
}
});
这段代码实现了两个主要功能：一是监听fetch事件，当请求的域名在允许列表中时，会添加自定义请求头后再发起请求；二是监听message事件，用于动态更新允许的域名列表。
三、配置编译输出
接下来要配置TypeScript的编译输出，修改项目根目录下的tsconfig.json文件：
{
"compilerOptions": {
"outDir": "build/sw",
"rootDir": "src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/sw.ts"]
}
这里设置了编译输出目录为build/sw，指定源文件目录为src，并启用了一些常用的编译选项。同时，通过include指定只编译src/sw.ts文件。
四、注册Service Worker
在src/App.tsx文件中注册Service Worker：
// src/App.tsx
import { useEffect } from 'react';
function App() {
useEffect(() => {
// 检查浏览器是否支持Service Worker
if ('serviceWorker' in navigator) {
const registerSW = async () => {
try {
// 注册Service Worker
const registration = await navigator.serviceWorker.register(
process.env.PUBLIC_URL + '/sw.js'
);
console.log('SW 注册成功:', registration);
} catch (err) {
console.error('SW 注册失败:', err);
}
};
// 开发环境热更新
if (process.env.NODE_ENV === 'development') {
const updateSW = () => {
navigator.serviceWorker.getRegistrations().then(registrations => {
// 遍历所有注册的Service Worker实例并更新
registrations.forEach(registration => registration.update());
});
};
// 每分钟检查一次更新
setInterval(updateSW, 60000);
}
// 执行注册操作
registerSW();
}
}, []);
return <div>App Content</div>;
}
export default App;
这段代码首先检查浏览器是否支持Service Worker，然后在支持的情况下进行注册。在开发环境中，还设置了每分钟检查一次Service Worker更新的机制。
五、配置构建脚本
为了方便构建项目，在package.json中添加构建命令：
{
"scripts": {
"build:sw": "tsc --project tsconfig.json",
"build": "npm run build:sw && react-scripts build",
"start": "react-scripts start && npm run build:sw -- --watch"
}
}
build:sw命令用于编译Service Worker相关的TypeScript代码；build命令先执行build:sw，再执行React项目的常规构建；start命令在启动React项目开发服务器的同时，监听sw.ts文件的变化并实时编译。
六、高级技巧拓展
（一）集成缓存策略
引入Workbox可以更好地管理缓存，提升应用性能。先安装workbox-build：
npm install workbox-build
然后创建workbox-config.js文件：
module.exports = {
globDirectory: 'build/',
globPatterns: ['**/*.{js,css,html,png}'],
swDest: 'build/sw.js',
clientsClaim: true,
skipWaiting: true
};
这个配置文件指定了要缓存的文件范围，以及生成的Service Worker文件的输出路径等选项。最后修改构建脚本：
{
"scripts": {
"build": "react-scripts build && workbox injectManifest workbox-config.js"
}
}
这样在构建项目时，Workbox会根据配置自动注入缓存相关的代码到Service Worker中。
（二）动态配置更新
可以通过网页向Service Worker发送消息来动态更新配置。在组件中添加如下代码：
// 在组件中
const updateSWConfig = () => {
if ('serviceWorker' in navigator) {
navigator.serviceWorker.controller?.postMessage({
type: 'UPDATE_DOMAINS',
domains: ['new-domain.com']
});
}
};
这段代码会向已注册的Service Worker发送消息，更新允许的域名列表。
（三）调试支持
在src/sw.ts中添加调试开关，方便开发时调试：
const DEBUG_MODE = process.env.NODE_ENV === 'development';
if (DEBUG_MODE) {
self.addEventListener('activate', (event) => {
console.log('[SW] 激活事件:', event);
});
}
当处于开发环境时，会监听activate事件并打印相关信息，帮助开发者了解Service Worker的运行情况。
七、使用过程中的注意事项
（一）作用域限制
Service Worker文件的位置很重要，要确保它位于网站根目录或子目录，并且其作用域能够覆盖到需要拦截请求的路径，否则可能无法正常工作。
（二）HTTPS要求
在生产环境中，必须使用HTTPS才能使用Service Worker。不过在本地开发时，可以通过localhost进行测试。
（三）更新机制
修改Service Worker代码后，需要重新编译，并且刷新页面才能使更新生效。也可以调用registration.update()方法来手动更新Service Worker。
（四）文件哈希
为了避免缓存问题，建议给编译后的Service Worker文件添加哈希值，比如命名为sw.[hash].js，这样在文件内容变化时，浏览器就会重新加载新的文件。
通过以上步骤和技巧，你就能在React项目中顺利地使用TypeScript编写Service Worker，有兴趣的朋友们可以试试啦。
